Wiki · Concept · Last reviewed June 25, 2026

Origin-Agent-Cluster

Origin-Agent-Cluster is a browser response-header mechanism for asking that a document run in an origin-keyed agent cluster rather than a broader site-keyed grouping.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser security, origin isolation, performance isolation, agents, web governance

Definition

Origin-Agent-Cluster is an HTTP response header defined in the HTML Standard. A secure-context document can send the header to request placement in an origin-keyed agent cluster. In that state, the document's agent cluster key is its origin rather than the broader site, and window.originAgentCluster returns whether the window belongs to such an origin-keyed cluster.

An agent cluster is part of the browser and JavaScript execution model: it groups related execution contexts that can share certain memory and synchronous communication capabilities. The practical point is not that a website controls the operating-system process model. The practical point is that a browser may use this origin-keyed boundary when allocating resources such as processes or threads, while exposing some web-developer-observable restrictions.

How It Works

The header uses Structured Field boolean syntax. The meaningful opt-in value is Origin-Agent-Cluster: ?1; values other than the true value are ignored by the HTML Standard's processing model. MDN describes the header as a request that the associated document be placed in an origin-keyed agent cluster, with resources shared only with documents from the same origin.

The observable consequences are narrower than the name suggests. If a document is in an origin-keyed agent cluster, attempts to relax the same-origin restriction with document.domain do nothing. The HTML Standard also says WebAssembly.Module objects cannot be sent to cross-origin documents, even when those documents are same-site. MDN's browser-facing documentation also lists same-site cross-origin transfer restrictions for SharedArrayBuffer and WebAssembly.Memory.

The browser also maintains consistency inside a browsing context group. The HTML Standard notes that the header cannot cause same-origin documents in that group to land in different agent clusters. This means window.originAgentCluster can return false even when a page sends the header, if an earlier same-origin page in the group settled the keying differently.

Agent Context

Origin-Agent-Cluster matters for browser agents because agents increasingly operate inside heavy web workspaces: code editors, media tools, dashboards, embedded sandboxes, video interfaces, and local model demos. A page that asks for origin-keying is saying that origin-level resource separation and reduced same-site synchronous reach matter to its operation.

An agent should not treat this header as a generic permission to trust the page. It should treat it as environmental evidence. If an automation task fails because document.domain is inert, a same-site iframe cannot be synchronously scripted, or a high-load embedded tool behaves differently from a sibling subdomain, the agent log should preserve the origin-keying state instead of collapsing it into a generic browser failure.

Governance Use

Governance use starts with a map of subdomains. Organizations often divide work across app.example.com, admin.example.com, chat.example.com, docs.example.com, and customer-specific origins. Origin-keying can help keep resource-intensive or risky same-site components from leaning on legacy synchronous access patterns. It can also reveal hidden coupling when old code depends on document.domain.

For agentic browser operations, record the top-level URL, child frame URLs, observed Origin-Agent-Cluster header, window.originAgentCluster value when measured, secure-context status, related COOP and COEP headers, browser version, task identifier, and the action that encountered the boundary. Strip secrets from URLs and do not preserve page contents unless the review actually needs them.

Limits

Origin-Agent-Cluster is not a full security boundary. MDN warns that browsers may ignore the request or implement it without memory protection, for example by using threads rather than separate processes. The header is better understood as a performance and execution-model hint with observable restrictions, not as a replacement for authentication, sandboxing, content security policy, cross-origin resource policy, or process-isolation guarantees.

It is also not the same thing as cross-origin isolation. The HTML Standard says documents whose cross-origin isolation mode is not none are automatically origin-keyed, and that the header may still be useful as an implementation hint, but adding it has no additional observable effects on author code in that situation. Audit the whole header set before assigning causality.

Minimum Evidence Record

For an investigation, preserve the response URL, exact Origin-Agent-Cluster value, secure-context status, window.originAgentCluster value, related COOP and COEP values, same-site frame or opener relationships, browser and version, task identifier, agent action, and whether any workaround changed frame access or proxying behavior. Keep only redacted URLs and minimal screenshots unless content evidence is required.

Source Discipline

Use the HTML Standard for the normative model: secure-context requirement, true-value processing, origin-keyed consequences, consistency within a browsing context group, and the relation to cross-origin isolation. Use MDN for implementation-facing syntax and operational cautions. Avoid claiming guaranteed process isolation unless the browser and platform being tested document that behavior for the exact release.

Spiralist Reading

Spiralism reads Origin-Agent-Cluster as a small refusal of inherited household privilege. A subdomain may share the family name, but it need not share every room, thread, and legacy shortcut with its siblings.

The agent-era lesson is that locality is not trust. A browser agent moving across related subdomains should notice when the page asks to be treated as its own origin-shaped unit. That request does not make the page safe. It does make the old assumption of same-site intimacy less reliable.

Sources

Return to Wiki