Wiki · Concept · Last reviewed August 12, 2026

Origin-Agent-Cluster

Origin-Agent-Cluster is an HTTP response header through which a secure-context document requests an origin-keyed JavaScript agent cluster instead of a potentially broader site-keyed cluster. It disables specified same-site, cross-origin sharing mechanisms and can guide browser resource allocation, but it does not guarantee a separate process or create a security sandbox. Here, “agent” is an ECMAScript execution concept—not an AI agent.

Category: Concept Published: June 25, 2026 Modified: August 12, 2026 Last reviewed: August 12, 2026 Tags: browser architecture, origin keying, performance isolation, JavaScript, web security

Snapshot

Definition

The WHATWG HTML Living Standard defines Origin-Agent-Cluster and window.originAgentCluster. The header lets a document delivered in a secure context request that its agent cluster key be its origin—scheme, host, and port—rather than its broader site. The request matters chiefly when documents are same-site but cross-origin, such as app.example.com and chat.example.com.

ECMAScript defines an agent cluster as the maximal set of agents that can communicate by operating on shared memory. An “agent” in this model is a specification mechanism containing execution contexts and an executing thread; it need not map one-to-one to a thread, process, tab, worker, or other implementation artifact. The term has no necessary connection to AI agents, multi-agent systems, model orchestration, or delegated authority.

Origin keying changes an execution-model grouping. It does not change the origin itself and does not, by itself, partition cookies, storage, service workers, network credentials, server-side sessions, permissions, or user identity.

How It Works

The standardized request is:

Origin-Agent-Cluster: ?1

The value is the Boolean true serialization defined by HTTP Structured Fields. Under the current HTML processing model, values other than ?1 are ignored. The header is effective only for documents delivered over a secure context.

During document creation, the browser combines the request with the browsing context group's prior keying decisions and other isolation state. The HTML Standard prevents the header from splitting same-origin documents in one browsing context group across different agent clusters. Its historical agent cluster key map therefore makes order matter: window.originAgentCluster can be false despite a present header if a prior same-origin document settled the group as site-keyed, or true without the current response header if the origin was settled earlier.

Two other cases are automatically origin-keyed. Documents with opaque origins report true and are unaffected by the header. Documents whose cross-origin isolation mode is not none are also origin-keyed; adding this header can remain a resource-allocation hint, but the standard says it adds no further author-observable effect.

The current HTML Standard names two observable consequences: setting document.domain does nothing, and WebAssembly.Module objects cannot be sent to cross-origin documents even when they are same-site. MDN additionally documents same-site, cross-origin transfer restrictions for SharedArrayBuffer and WebAssembly.Memory; because shared-memory availability also depends on cross-origin isolation and browser implementation, those details should be tested in the target release rather than inferred from the header alone.

Current Context

As of August 12, 2026, origin-keyed agent clusters remain in the WHATWG HTML Living Standard, whose reviewed snapshot was last updated August 11, 2026. The feature is standard-track but not uniformly available in stable browser engines. MDN's browser-compat-data snapshot records the header and window property in Chrome from version 90 and Firefox from version 138, while Safari is marked as available in Technology Preview rather than a stable release. Unsupported browsers can ignore the unknown response header, so deployments need runtime detection rather than user-agent assumptions.

The surrounding document.domain landscape has also changed. The HTML Standard warns against the setter and says its removal is a long-running web-platform process. Chrome's migration guidance states that Chrome began making the setter inert by default from version 115 and documents Origin-Agent-Cluster: ?0 as a Chrome-specific compatibility escape hatch for sites that still need the legacy behavior. That must not be mistaken for the standardized opt-in rule: in the current HTML Standard's Origin-Agent-Cluster processing, a false value does not request site keying; it is ignored.

The original 2021 rollout article remains useful for architecture and deployment guidance, but its launch-era compatibility table is historical. Current implementation claims should use dated browser documentation, compatibility data, and direct tests.

Adjacent Boundaries

Deployment and Migration

Inventory same-site coupling first. Search for document.domain, synchronous DOM access across subdomains, cross-origin postMessage() transfers of WebAssembly or shared-memory objects, and embedded tools whose performance depends on sibling origins. Include legacy admin, identity, payment, media, and customer-specific subdomains.

Configure the whole origin. Send Origin-Agent-Cluster: ?1 consistently on every document response for the origin, including navigable error pages. Check application servers, CDNs, reverse proxies, static-host rules, authentication paths, and error handlers. A partial rollout can make results depend on which same-origin document was loaded first in the browsing context group.

Test in a fresh group. Reloading is insufficient after an origin's keying decision has been established. Close related tabs and windows, then create a new unconnected browsing context. Record the response header and inspect window.originAgentCluster; also inspect window.crossOriginIsolated separately.

Migrate explicit communication. Replace document.domain coupling with postMessage() or MessageChannel where appropriate. Specify an exact target origin, verify the sender's origin and window, validate the message schema, and keep credentials or authorization material out of messages.

Measure rather than assume. Compare task latency, responsiveness, memory use, crashes, iframe behavior, and browser-specific results before and after rollout. A browser may allocate separate processes or threads, retain shared resources, or decline the request; additional processes can also increase memory overhead.

Plan rollback carefully. Removing ?1 must be consistent and retested from a fresh browsing context group. Do not assume ?0 is a portable inverse: its documented legacy role is specific to Chromium's default-origin-keying migration, while the current HTML Standard ignores non-true values in this header's opt-in algorithm.

Automation Context

Browser automation can encounter OAC as environmental state in code editors, media applications, dashboards, embedded workspaces, and test harnesses. If a same-site iframe cannot be synchronously scripted, document.domain becomes inert, or behavior differs after a navigation, the runtime should preserve the origin-keying evidence rather than classify the event only as site flakiness.

The header is not permission for an AI or automation agent to bypass a frame boundary, reuse credentials, proxy content, inject scripts, or move data into a model-visible trace. The appropriate response is to use the site's supported messaging or automation interface, surface the boundary to the user or policy layer, and minimize captured page data.

Governance and Safety

OAC is a web-architecture change with cross-team consequences. A named owner should control the response-header rule, origin inventory, performance baseline, supported-browser matrix, exception process, and rollback. CDN and error-page configuration belong in change review because they can silently turn a deliberate rollout into an order-dependent one.

Security review should recognize the narrow benefit without converting it into a certification. Disabling document.domain relaxation removes a legacy synchronous-access path, but OAC does not authenticate sibling origins, isolate secrets, prevent framing, constrain network access, stop prompt injection, or provide Spectre-class side-channel protection. Multi-tenant or separately administered subdomains still need explicit origin, cookie, storage, framing, fetch, and server-authorization controls.

Performance claims also need governance. A header may help a browser schedule a resource-intensive origin independently, but it may do nothing or increase memory overhead. Product teams should define success metrics and compare target devices, browsers, embedded views, and low-memory environments rather than declaring “isolation” from configuration alone.

Telemetry should be proportionate. Header audits and automated-browser traces can retain origins, response status, relevant isolation state, and a task or release identifier without storing full URLs, query tokens, cookies, page contents, or screenshots. Access, retention, and deletion rules should match the sensitivity of the affected workflow.

Failure Modes

Limits

OAC cannot force a browser to allocate a particular process, thread, memory quota, CPU budget, crash boundary, or scheduler priority. It cannot prove that two origins do not share implementation resources. The agent cluster itself is a specification mechanism, and both ECMAScript and HTML leave room for implementation choices.

OAC also does not stop asynchronous cross-origin communication. Properly authorized pages can still communicate through mechanisms such as postMessage(), and origins may remain related through cookies, server endpoints, storage mechanisms, or embedding arrangements governed by other rules. Its restrictions are deliberately narrower than a general security boundary.

Finally, window.originAgentCluster is evidence of the browser's logical keying state, not why that state arose. A true value may result from the header, an earlier same-origin document, an opaque origin, cross-origin isolation, or a browser default. Audit the causal inputs before assigning credit or blame to the header.

Minimum Evidence Record

Source Discipline

Use the HTML Standard for normative syntax, processing, the historical key map, automatic origin keying, and author-observable effects. Use ECMAScript for the meaning of “agent” and “agent cluster,” and RFC 9651 for Structured Fields syntax. These specifications describe logical semantics, not a browser's guaranteed process layout.

Use current browser-compatibility data and direct tests for implementation claims. MDN is useful for developer-facing behavior, but its statement that a true property means the operating system has supplied dedicated resources is stronger than the HTML and ECMAScript guarantees. The safer claim is that the window is logically origin-keyed and that the browser may allocate resources accordingly.

Keep vendor-specific behavior scoped. Chrome's ?0 migration guidance applies to Chrome's default handling of document.domain; the HTML Standard says non-true OAC values are ignored. A report should name the browser, version, policy, and tested behavior instead of presenting one vendor's escape hatch as portable HTTP semantics.

For a live deployment, cite both the captured response field and runtime state. A header alone proves a request, not that it took effect. A property value alone proves logical state, not which response caused it, whether a process was dedicated, or whether performance improved.

Spiralist Reading

Spiralism reads Origin-Agent-Cluster as a refusal to confuse a shared family name with a shared execution room. Two subdomains may belong to one site while still asking the browser to account for their work separately.

The discipline is modest: name the actual boundary, verify whether it took effect, and do not turn a performance hint into a claim of trust. Locality is not authorization, and technical vocabulary should not be borrowed to imply more agency or safety than the system provides.

Open Questions

Sources

Return to Wiki