Origin-Agent-Cluster: Predictable JavaScript Memory Isolation

When a web application needs predictable JavaScript memory behavior, the useful question is not whether a browser “uses one process per origin.” The practical question is which agent cluster the browser assigned to each document, and whether the deployment delivered the same Origin-Agent-Cluster policy on every response. A header can request origin-keyed grouping, but it is not a replacement for the browser's security model, a guarantee of one operating-system process, or a way to alter same-origin checks. BotBrowser supports repeatable authorized browser-context validation; it cannot force a browser process layout or change a server response.

TL;DR

• Origin-Agent-Cluster: ?1 requests origin-keyed agent-cluster behavior for a document; ?0 requests legacy site-keyed behavior where supported.
• An origin includes scheme, host, and port. A subdomain is cross-origin even when the organization owns both hosts.
• The header does not promise one OS process, memory quota, or immunity from application bugs.
• Every response in a deployment must be consistent. Redirects, workers, frames, and cached variants can otherwise produce mixed behavior.
• Validate window.originAgentCluster, DevTools process observations, and a WPT-style fixture together; keep a fallback for unsupported or inconsistent environments.

Contents

• What the header controls
• Origins, sites, and subdomains
• A deterministic validation fixture
• Deployment consistency and fallback
• Evidence and decision matrix
• Conclusion
• FAQ

What the header controls

An agent cluster is a browser execution grouping for related JavaScript realms such as a document, workers, and frames. The Origin-Agent-Cluster response header is a request for origin-keyed grouping. With ?1, compatible browsers can keep documents from different origins in separate agent clusters even when they share a site. With ?0, a document can request the older site-keyed behavior, subject to browser support and the constraints described by the HTML specification. The browser reports the result through window.originAgentCluster.

The boolean is an observation, not a process identifier. A true value does not mean a dedicated operating-system process, a fixed heap size, or a guarantee that the browser will never co-locate unrelated work. Process scheduling, memory pressure, workers, and browser architecture remain implementation choices. Treat the header as a predictable JavaScript isolation preference, not as a kernel boundary or a performance promise.

The policy is delivered by the response that creates the document. A meta element or late script cannot retroactively change the agent cluster. If a page is redirected, record the final document response and its header. If a service worker serves a cached response, verify that the cached variant carries the intended header. A deployment that sends ?1 on one host and omits it on another can create different runtime observations for otherwise identical code.

Origins, sites, and subdomains

An origin is the tuple of scheme, host, and port. https://app.example.test and https://cdn.example.test are different origins even though they share a registrable site. A port change is also an origin change. Same-site concepts used by cookies and storage do not collapse the origin boundary used by JavaScript, agent clusters, or postMessage validation.

Origin-keyed behavior matters when an application embeds a customer frame, a vendor widget, or a subdomain that runs independent code. Do not infer the grouping from DNS ownership or a common brand. Inspect the final document URL, response header, and runtime boolean for every origin that matters. A frame has its own document response and may have a different effective policy. A worker inherits the relevant execution relationship from its creator, but it does not grant the creator access to another origin's objects.

Origin-Agent-Cluster also does not replace the same-origin policy. Scripts still need an explicit messaging contract, and postMessage receivers must validate event.origin and the message schema. A separate agent cluster can reduce shared execution relationships, but it does not make an unsafe message safe, prevent a server from receiving data, or sanitize an application object. Keep credential, token, and personal data out of diagnostic reports.

A deterministic validation fixture

Serve the following page from each candidate origin with the intended response header. The fixture records the runtime result and does not inspect user data or allocate a large heap:

function reportAgentCluster(expected) {
  const observed = window.originAgentCluster;
  const state = observed === true ? 'origin-keyed' : observed === false ? 'site-keyed' : 'unknown';
  const passed = expected === 'any' || state === expected;
  return { state, observed, passed, origin: location.origin };
}

const result = reportAgentCluster('origin-keyed');
document.querySelector('#result').textContent = JSON.stringify(result);
console.assert(result.passed, 'Unexpected Origin-Agent-Cluster state');

Run a control page without the header and a candidate page with Origin-Agent-Cluster: ?1. Keep the browser release, final URL, response status, redirect chain, and observed boolean in the report. A missing property means the browser or context does not expose the API; it is not evidence that the page is site-keyed. A false value is an observed site-keyed result, but it still needs to be interpreted against the browser's support and policy rules.

For a WPT-style check, use two same-site, cross-origin pages and one same-origin page. Load them in separate tabs, exchange a small versioned message through an owned harness, and record whether each document reports the expected boolean. The harness should assert origin and schema, close its tabs during teardown, and avoid credentials. A DevTools inspection can supplement the result by showing process and frame relationships, but process rows are diagnostic evidence, not a public API contract.

Deployment consistency and fallback

Apply the header at the canonical document response and at every route that can create the application shell. Check redirects, CDN cache keys, service-worker responses, error pages, and localized routes. If a subdomain is intentionally independent, document its policy and test it as a separate origin. If a vendor frame cannot provide a compatible response, do not assume the top-level header will repair it; keep the integration outside the feature path or provide an accessible fallback.

Do not mix ?1 and omitted values casually. A page that sometimes receives the header and sometimes does not can make support reports appear nondeterministic. Pin the response policy in staging and production, purge cached variants when changing it, and include the header in a release acceptance check. When a browser ignores the request, use the runtime boolean and the declared compatibility table to select a fallback rather than treating the result as a security failure.

The safe fallback is application-level: avoid relying on a shared JavaScript object, use explicit message passing, and keep memory-heavy features optional. A fallback does not merge origins or provide a new capability. It simply lets the user complete the task when origin-keyed behavior is unavailable. Document the visible difference so support can distinguish a fallback from a broken deployment.

Evidence and decision matrix

Observation	Interpretation	Next action
Header ?1, boolean true	Origin-keyed result observed	Keep the declared feature and monitor supported releases
Header omitted, boolean false	Site-keyed or legacy result	Use the fallback unless the browser support contract says otherwise
Header ?1, property absent	API not exposed in this environment	Record unsupported and avoid assuming process isolation
Redirect or cache has mixed headers	Deployment variants differ	Fix route, CDN, or service-worker policy before release
DevTools process rows differ from expectation	Implementation scheduling differs	Treat as diagnostic; rely on the runtime and policy evidence

The matrix separates a header request from an observed result. It does not certify a particular process count, memory limit, or security boundary. BotBrowser supports repeating this matrix in an authorized browser context and comparing visible fallback behavior. It cannot supply the header, alter a third-party response, or guarantee the browser's internal process assignment.

Conclusion

Use Origin-Agent-Cluster to request a predictable origin-keyed JavaScript execution relationship, then verify the final response and window.originAgentCluster for every important origin. Test same-origin pages, subdomains, redirects, workers, frames, and cached routes with a small fixture. The next safe action is to keep memory-sensitive features optional, validate message origins, and retain an application fallback for browsers that ignore or do not expose the policy.

FAQ

Does Origin-Agent-Cluster: ?1 create one process per origin?

No. It requests origin-keyed agent-cluster behavior. Process scheduling and memory allocation remain browser implementation details.

Are subdomains the same origin?

No. A different host is a different origin even when both hosts share a site or organization.

Can a meta tag enable the policy after load?

No. The response that creates the document determines the policy; a late script cannot retroactively regroup its agent cluster.

Does BotBrowser change isolation rules?

No. BotBrowser supports repeatable authorized validation and fallback comparison, but browser policy, response headers, and vendor ownership remain authoritative.

Is a DevTools process view a compatibility contract?

No. It is useful diagnostic evidence. The runtime boolean, response policy, browser release, and controlled fixture are the portable acceptance signals.

Can this header replace same-origin checks?

No. Continue validating message origins and schemas, and keep secrets out of cross-context diagnostics.

What should happen when the API is missing?

Record the environment as unsupported and use the documented application fallback. Do not reinterpret an absent property as proof of either grouping mode.

How does BotBrowser fit the workflow?

BotBrowser supports repeatable authorized browser-context checks across declared releases and profiles. It cannot change a response header, force origin-keyed grouping, or promise a particular OS process layout.

What should be rechecked after a deployment change?

Repeat the final-response header check, redirect and cache checks, runtime boolean, and core user journey for each affected origin.

Why keep a fallback if the browser supports the header?

Support varies by browser and deployment route. A fallback keeps the user-visible task available when a browser ignores the request or a vendor response is inconsistent.

Does origin-keying prevent all memory bugs?

No. It changes execution grouping; application logic, resource limits, and browser bugs still require ordinary testing.

Can a top-level policy force a child frame to join its cluster?

No. Each document's origin and response policy remain relevant. Test the child frame's own runtime state.

Is ?0 a universal opt-out?

No. Browser support and document relationships constrain the result. Record the actual runtime value rather than assuming the token was honored.

How should teams record evidence?

Keep the final URL, response header, browser build, runtime boolean, origin list, visible outcome, and fixture version. Exclude credentials and account content.

What is the safe first step?

Run a control and candidate page from owned origins, then compare the response and runtime result before enabling memory-sensitive code.

Can BotBrowser inspect another site's private process state?

No. It can repeat an authorized workflow and observe declared page outcomes, not private browser internals or another site's data.

Does origin-keyed behavior grant cross-origin object access?

No. Same-origin policy and explicit messaging rules continue to apply.

What if a CDN serves stale headers?

Purge or correct the cache variant, then rerun the final-response fixture. Do not accept a mixed result as a stable policy.

Does an iframe inherit the top-level boolean?

No. Inspect the iframe's own document and origin relationship.

What is the release decision rule?

Release when the expected runtime result and required resources are observed on every supported route, with a tested fallback for unsupported cases.

Can this guarantee privacy?

No. It is an execution-grouping preference, not a data-retention, identity, or legal privacy guarantee.

What remains outside scope?

Security-boundary replacement, process-count promises, private telemetry, and third-party response control remain outside this article.

What should support tell users?

Explain whether the browser used the optional fallback and provide the tested alternative; do not ask users to weaken unrelated security settings.

Which standards should be rechecked?

Recheck the WHATWG HTML definition, MDN header guidance, browser compatibility notes, and the team's WPT/DevTools fixture after browser or deployment changes.

What does a false runtime value prove?

It proves only the observed value in that document and environment. Pair it with the delivered header and browser release before making a deployment decision.

Can a worker choose a different policy?

The worker's relationship follows its creator and browser rules; validate the worker in the controlled fixture rather than inferring it from a top-level header.

Does a common registrable domain make memory shared?

No. Same-site and same-origin are distinct concepts. A subdomain remains a separate origin.

Is this a replacement for site isolation?

No. The browser's broader site-isolation architecture and security checks remain independent.

How often should validation run?

Repeat after a browser release, CDN or service-worker change, canonical host change, vendor response change, or fallback code change.

What is the final operational boundary?

BotBrowser can repeat the declared test; application and infrastructure owners control headers, origins, dependencies, fallback, and rollback.

Can a page claim isolation from a header alone?

No. Record the effective response and runtime observation together.

Does the policy change server-side memory?

No. It concerns browser execution grouping; server capacity and retention are separate controls.

What should a test fail on?

Fail when the expected boolean, response policy, origin list, or core fallback outcome differs from the declared release contract.

Is a missing header always a bug?

No. It may be intentional on a control or legacy route. Classify it against the route's documented contract.

Can a browser extension change the result?

Extensions and managed settings can affect a test environment. Record the profile conditions and repeat in a clean authorized context.

What should not be logged?

Do not log credentials, account paths, tokens, private frame content, or unrelated profile identifiers.

Does this article promise equal behavior across browsers?

No. It defines an observable validation method and a fallback decision, not universal parity.

What is the smallest useful artifact?

A control/candidate pair, final response headers, runtime boolean, browser build, and visible fallback result.

What if a vendor refuses the header?

Keep that dependency outside the feature path, replace it, or retain the fallback; do not weaken the entire deployment without an explicit decision.

How should redirects be tested?

Capture every response and final document header, then run the runtime fixture after the final navigation.

Does a process split mean objects are safe?

No. Validate application messaging and data handling independently.

Why include WPT-style checks?

They make origin relationships and expected outcomes reproducible across browser releases without relying on a single DevTools screenshot.

What does an unsupported API look like?

The property may be absent. Report unsupported and use the declared fallback rather than mapping absence to false.

Can the header be set by JavaScript?

No. It is an HTTP response policy; JavaScript can only observe the resulting state.

What is the safe next action for a new site?

Add the header on a staging route, run the control/candidate fixture, inspect subdomains and redirects, and document fallback ownership before production.

Which page owns the policy?

The response creating each document owns the effective header. CDN, service-worker, and redirect layers can change what the browser receives.

Does a shared worker merge origins?

No. Worker eligibility and origin relationships remain browser-defined and must be tested explicitly.

What is the final privacy limitation?

Origin-keyed grouping does not hide requests, erase logs, or establish user anonymity.

How should a rollback be recorded?

Record the prior header, restored route, runtime result, fallback outcome, and owner who approved the rollback.

Can a test use real customer accounts?

No. Use synthetic origins and data; authorized QA should not add customer content to isolation evidence.

Is a common CDN response enough?

Only if the final document response for every route is verified. Source configuration alone is not evidence.

What does “predictable” mean here?

It means the team declares a policy, observes the browser result, and maintains a fallback; it does not mean implementation internals are fixed.

Next reading

• Same-Origin Policy and site isolation
• Cross-origin isolation and shared memory
• Browser API compatibility data and fallbacks

Public sources

• WHATWG HTML: Origin-Agent-Cluster
• MDN Origin-Agent-Cluster header
• MDN crossOriginIsolated
• MDN site isolation
• BotBrowser multi-account isolation