A New Header for Isolating Your Origin's Resources

The Origin-Agent-Cluster HTTP response header is now available in Chrome 88 and later. It requests that the browser place your page in an origin-keyed agent cluster instead of the default site-keyed one. This gives the browser a hint that your origin deserves dedicated resources like its own process, and it also disables certain legacy synchronous scripting abilities between same-site cross-origin pages.

You can safely send this header to all users today. Browsers that don't recognize it will ignore it without issue, and since origin-keyed clusters restrict fewer features than the default site-keyed behavior, there are no interoperability concerns.

Why Browsers Can't Automatically Separate Subdomains

Modern browsers divide different origins into separate processes for performance and stability, but the heuristics they use to limit process count are imperfect. Crucially, they can't fully segregate subdomains like https://sub.a.example from https://a.example — these share a site, and exceptions to the same-origin policy allow them to communicate.

This default grouping is called a "site-keyed agent cluster." The new header lets a page opt out of that grouping and into an origin-keyed agent cluster, which only includes pages with the exact same origin. That opt-in separation allows the browser to give your origin its own dedicated resources without risking conflicts with other origins on your site.

What You Give Up by Opting In

Requesting performance isolation requires disabling some legacy features in exchange for the browser's adherence to your request. Specifically, a page in an origin-keyed agent cluster can no longer:

  • Set document.domain, which previously allowed same-site cross-origin pages to synchronously access each other's DOM
  • Send WebAssembly.Module objects to other same-site cross-origin pages via postMessage()
  • In Chrome only, send SharedArrayBuffer or WebAssembly.Memory objects to other same-site cross-origin pages

Who Benefits Most

Origins that are best suited for origin-keyed agent clusters generally fit one of these profiles, per the spec's design:

  • Resource-hungry single origins: Such as performance-intensive games, video conferencing sites, or multimedia creation apps that perform best when they can claim a separate process.
  • Embedders of same-site iframes: For example, https://mail.example.com embedding https://chat.example.com iframes, where origin-keying the top-level page can prevent the embedded team's code from impacting your own performance and could lead to independently scheduled processes.
  • Resource-heavy embedded widgets: If https://customerservicewidget.example.com relies on expensive features like video chat and is embedded on various https://*.example.com origins, sending the header may limit its impact on embedders.

You should also verify you're comfortable disabling the rare cross-origin communication features mentioned above and confirm your site uses HTTPS.

These guidelines are only a starting point. Whether origin-keying improves your site's performance depends on your specific usage. You should measure your Web Vitals and memory usage before and after enabling it — additional processes can increase memory overhead. Don't roll this out without validation.

Relationship to Cross-Origin Isolation

Origin-keying is conceptually related to, but distinct from, cross-origin isolation via Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers. Both mechanisms disable the same same-site cross-origin communication features, so a cross-origin isolated site has already accepted those constraints. However, you should still consider applying Origin-Agent-Cluster even if your site is cross-origin isolated, as it provides an additional hint to the browser's resource allocation heuristics.

Deployment and Verification

Configure your web server to send the header on every response:

Origin-Agent-Cluster: ?1

The ?1 value is the structured header syntax for a boolean true.

The header must be present on all responses from your origin, not just specific pages. The browser remembers what it has previously seen for a given origin — including when it did not see the header — to ensure consistent keying across all same-origin pages. Any inconsistency and the browser will ignore the header, with a console warning in Chrome. This "memory" is tied to a specific browsing context group, which is why simply reloading won't work when you first add the header; you'll need to close the tab completely and open a fresh one.

To confirm the header is working correctly, check the window.originAgentCluster JavaScript property. It returns true when origin-keying is active, false when it isn't, and undefined in browsers without support for the property. Sending this value to your analytics can be a useful deployment check.

Note that the header only functions in secure contexts — HTTPS pages or http://localhost. It will not work on non-localhost HTTP pages.

What origin-keying does not do

It's important to understand that origin-keyed agent clusters do not provide the same protections as security-focused headers like Cross-Origin-Resource-Policy or Cross-Origin-Opener-Policy. In particular, origin-keying should not be treated as a reliable defense against side-channel attacks such as Spectre.

This may seem counterintuitive, since origin-keying can sometimes result in your origin receiving its own process, and process isolation is a key defense against side-channel attacks. But the Origin-Agent-Cluster header is only a hint to the browser, which has no obligation to act on it. A browser may decline to allocate a separate process for several reasons:

  • The browser may not support process isolation for all contexts. For instance, Safari and Firefox currently isolate separate tabs but cannot yet do so for iframes.
  • On resource-constrained environments, such as low-memory Android devices or Android WebView, Chrome minimizes process count regardless of the header.
  • The browser may honor the isolation request using technology other than processes. Chrome is exploring thread-based isolation for this purpose.
  • A prior navigation to a site-keyed page on your origin can trigger the consistency guarantee, causing the Origin-Agent-Cluster header to be ignored entirely.

So it's best to think of origin-keyed agent clusters not as a security mechanism, but as a signal that helps the browser prioritize resource allocation. By sending the header, you're indicating that your origin would benefit from dedicated resources, and that you accept the trade-offs of losing certain features in exchange.

Getting involved and tracking the feature

If you're using or evaluating the Origin-Agent-Cluster header, the Chrome team welcomes your feedback. Sharing your interest publicly helps prioritize development and demonstrates demand to other browser vendors. You can reach Chrome DevRel on Twitter at @ChromiumDev.

For questions about the specification, file an issue on the HTML Standard GitHub repository. To report bugs in Chrome's implementation, use new.crbug.com with the Components field set to Internals>Sandbox>SiteIsolation.

To go deeper into origin-keyed agent clusters, check out these resources: