Origin-Agent-Cluster
Learn how to control origin agent cluster behavior for improved isolation.
Origin-Agent-Cluster is a security header that controls whether a page runs in its own origin agent cluster. This header improves isolation between origins and helps prevent cross-origin attacks.
What is Origin-Agent-Cluster?#
Origin-Agent-Cluster is a security header that tells the browser to give your page its own dedicated process group (called an 'agent cluster'), separate from pages on other origins. In simple terms, it requests that the browser keep your site's pages isolated from other sites at the process level. This provides better security boundaries and can improve performance by reducing resource contention between different sites.
- Requests that the browser isolate your origin into its own agent cluster
- Provides better security boundaries between your site and other origins
- Can improve performance by reducing contention with other sites' pages
- Uses the structured header boolean syntax: ?1 to enable, ?0 to disable
An agent cluster is a browser concept that groups pages and workers that can communicate directly with each other. By default, pages from the same site (like app.example.com and api.example.com) may share an agent cluster. Origin-Agent-Cluster requests that only same-origin pages share a cluster, providing stronger isolation.
Why Origin Isolation Matters#
Without Origin-Agent-Cluster, browsers may group pages from the same site (but different subdomains) into a shared process. While convenient for communication between subdomains, this reduces security isolation. If one subdomain is compromised, shared processes could make it easier for an attacker to affect other subdomains.
- Shared processes between subdomains reduce the security boundary between them
- A compromised subdomain in a shared cluster could more easily affect other subdomains
- Process isolation limits the impact of memory-based vulnerabilities like Spectre
- Dedicated processes prevent resource exhaustion on one origin from affecting others
Implementation Guide#
Enabling Origin-Agent-Cluster is simple. Set the header to ?1 on your server responses. Note that once enabled, certain cross-origin communication features (like document.domain assignment) become unavailable.
Enabling Origin-Agent-Cluster prevents your page from setting document.domain to communicate with pages on sibling subdomains. If your application relies on document.domain for cross-subdomain communication (a legacy technique), enabling this header will break that functionality.
# Apache
Header always set Origin-Agent-Cluster "?1"
# Nginx
add_header Origin-Agent-Cluster "?1" always;
# Node.js / Express
app.use((req, res, next) => {
res.setHeader('Origin-Agent-Cluster', '?1');
next();
});Best Practices#
Follow these guidelines when deciding whether to enable Origin-Agent-Cluster for your application.
- Enable ?1 if your site does not use document.domain for cross-subdomain communication
- Verify that no pages on your site set document.domain before enabling
- Combine with COOP and COEP for comprehensive origin isolation
- Modern applications should use postMessage instead of document.domain for cross-origin communication
- The header is a hint to the browser, not a guarantee, as process allocation depends on browser resources
Implementation Examples#
Enable Origin Isolation
Origin-Agent-Cluster: ?1Enables origin agent cluster isolation
Explanation: This ensures the page runs in its own origin agent cluster, providing better isolation.
Disable Origin Isolation
Origin-Agent-Cluster: ?0Disables origin agent cluster isolation
Explanation: This allows the page to share processes with other origins.
Key Directives#
?1
Enables origin agent cluster isolation
?1?0
Disables origin agent cluster isolation
?0References#
Test Your Origin-Agent-Cluster Configuration
Scan your site to check if Origin-Agent-Cluster is properly configured.