Origin-Agent-Cluster security response

What it does

Origin-Agent-Cluster requests that the browser place the responding origin into its own dedicated "agent cluster" — essentially requesting stronger process-level isolation than the browser's default behavior provides. Browsers group related pages into agent clusters (roughly, isolated execution contexts) for security and resource management, but by default this grouping can happen at the site level (covering all subdomains of a registrable domain) rather than the more granular origin level (scheme + host + port exactly).

Setting this header requests origin-level isolation specifically — meaning app.example.com and blog.example.com, even though they're the same "site," can be guaranteed separate agent clusters rather than potentially sharing one.

Syntax

Origin-Agent-Cluster: ?1

The value is a structured-fields boolean — ?1 means "yes, request origin-keyed isolation." There's no meaningful ?0 value in practice; you either send the header requesting isolation or omit it entirely to accept default behavior.

What origin-keyed isolation provides

• Stronger memory isolation — origin-keyed agent clusters give the browser a stronger guarantee it can allocate separate OS-level processes per origin, reducing the blast radius of certain memory-corruption or side-channel classes of vulnerability (like Spectre-style attacks) between origins that happen to share a site.
• Access to higher-precision timers — some high-resolution timing APIs (relevant for performance measurement, but also historically abused for timing-attack side channels) are gated behind stronger isolation guarantees; requesting origin-keying can unlock access to more precise timing APIs than would otherwise be available.
• Preventing document.domain relaxation — pages that opt into origin-keyed agent clusters lose the ability to use the legacy document.domain trick (historically used to relax same-origin restrictions between subdomains) — this is a deliberate trade-off, since origin-keying and document.domain relaxation are conceptually incompatible.

Common mistakes and gotchas

Expecting a guaranteed separate OS process. The header is a request, not a guarantee — browsers use origin-keying as a strong signal for how to allocate isolation resources, but the exact process allocation strategy remains a browser implementation detail that can vary by browser, platform, and system resource constraints.

Setting this header while relying on document.domain. If your application (or an embedded third-party script) depends on the legacy document.domain cross-subdomain relaxation trick, requesting origin-keyed isolation will break that capability — the two are mutually exclusive by design.

Assuming this replaces Cross-Origin-Opener-Policy or Cross-Origin-Embedder-Policy. These headers address related but distinct isolation concerns — Origin-Agent-Cluster is about process/agent-cluster isolation, while COOP/COEP govern cross-origin window references and resource loading needed for features like SharedArrayBuffer. Sites pursuing strong isolation (for high-precision timing, cross-origin isolation state) commonly need to combine several of these headers together, not rely on just one.

Not testing across multiple browsers. Since the actual isolation behavior is implementation-defined, testing that your application behaves correctly (and gains the intended benefits) across different browsers is worthwhile rather than assuming uniform behavior.

Real-world examples

Requesting origin-keyed isolation:

HTTP/1.1 200 OK
Origin-Agent-Cluster: ?1

Combined with related cross-origin isolation headers for high-precision timing access:

HTTP/1.1 200 OK
Origin-Agent-Cluster: ?1
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

FAQ

Does Origin-Agent-Cluster guarantee my origin gets its own OS process?

Not with absolute certainty — it's a strong hint/request to the browser, and the actual isolation strategy (including whether a truly separate process is allocated) remains a browser implementation detail that can vary.

What's the difference between origin-keyed and site-keyed agent clusters?

Site-keyed grouping (the more common default) can bundle all subdomains of a registrable domain (example.com, app.example.com, blog.example.com) into one shared agent cluster. Origin-keyed grouping, requested by this header, isolates by the exact origin (scheme + host + port), so those same three subdomains would each get their own isolated cluster.

Why would I want origin-level isolation instead of the default?

Stronger security isolation between subdomains that might have different trust levels (a marketing blog vs. a logged-in application on the same registrable domain), and access to higher-precision timing APIs that are gated behind stronger isolation guarantees.

Does setting this header break anything?

Mainly the legacy document.domain cross-subdomain relaxation mechanism — if your application or any embedded third-party code relies on that, requesting origin-keyed isolation will disable that capability, since the two features are architecturally incompatible.

Fun fact

The document.domain incompatibility this header introduces is a deliberate, hard trade-off the browser vendors made rather than an accidental limitation — document.domain relaxation has been considered a long-standing security wart in the web platform for years (it lets same-site-but-different-origin pages opt into weaker isolation after the fact), and Origin-Agent-Cluster was partly designed as a forcing function to help the platform eventually move away from that legacy mechanism entirely, by making strong isolation and document.domain mutually exclusive rather than trying to support both simultaneously.