Policy reference

Browser policy lets you put a managed browser inside an explicit operating boundary. Use it to describe where a browser may navigate, which auth or redirect excursions are expected, what private-network access is allowed, and how downloads, uploads, and destructive actions should be handled.

const policy = {
  mode: "strict",
  allowedDomains: ["vendor.example"],
  authDomains: ["login.vendor.example"],
  redirectDomains: ["cdn.vendor.example"],
  downloads: { mode: "requireApproval", maxBytes: 25_000_000 },
  uploads: { mode: "requireApproval", allowedMimeTypes: ["application/pdf"] },
  approvals: { destructiveActions: "requireApproval" },
} satisfies BrowserNavigationPolicy;

Where policy is accepted

Surface	How to pass policy
TypeScript SDK client default	`new Web({ policy })`
TypeScript SDK browser create	`web.browser.create({ policy })`
TypeScript SDK agent default	`web.agent({ browser: { policy } })`
TypeScript SDK agent browser creation	`web.agent({ browser: { create: { policy } } })`
TypeScript SDK quick actions	`web.scrape({ policy })`, `web.screenshot({ policy })`, `web.pdf({ policy })`
CLI `web agent`	`--allow-domain <domain>` sets `allowedDomains` only.
CLI `web mcp run`	`--allow-domain`, `--allow-origin`, and `--private-access localhost` create a default MCP browser policy.
MCP `manage_browsers`	`policy` object on `action: "create"`.
REST API	Browser-create and quick-action request bodies expose policy fields in the OpenAPI spec.

`BrowserNavigationPolicy`

interface BrowserNavigationPolicy {
  mode?: "strict" | "guided";
  allowedDomains?: string[];
  blockedDomains?: string[];
  authDomains?: string[];
  redirectDomains?: string[];
  allowedOrigins?: string[];
  blockedOrigins?: string[];
  privateAccess?: "trusted-domains" | {
    domains?: string[];
    cidrs?: string[];
    localhost?: boolean;
  };
  downloads?: BrowserDownloadPolicy;
  uploads?: BrowserUploadPolicy;
  approvals?: BrowserApprovalRules;
}

Field	Description
`mode`	Navigation policy mode. Accepted values: `strict` and `guided`. Defaults to `strict` when a policy is normalized.
`allowedDomains`	Domain boundary. A domain entry matches the exact hostname and its subdomains.
`blockedDomains`	Domains that are denied before allow/auth/redirect checks.
`authDomains`	Domains the browser may enter from an allowed boundary for authentication. Auth-domain content access is treated as an excursion that should return to an allowed domain.
`redirectDomains`	Domains the browser may enter from an allowed boundary for expected redirects.
`allowedOrigins`	Exact origin boundary: protocol, host, and port.
`blockedOrigins`	Origins denied before allow/auth/redirect checks.
`privateAccess`	Private-network access grant. See Private access.
`downloads`	Download controls.
`uploads`	Upload controls.
`approvals`	Default approval rules for deterministic risk classes.

Modes

Mode	Behavior
`strict`	Keep the browser inside policy and return policy tips when a navigation or content access is blocked.
`guided`	Still evaluates policy, but policy tips may include suggested additions such as `authDomains` or `redirectDomains` to help you refine the policy.

mode, authDomains, redirectDomains, and privateAccess require an explicit allowed boundary through allowedDomains or allowedOrigins.

Domains and origins

Use domains for most browser-agent work:

{ allowedDomains: ["example.com"] }

Domain entries:

Rule	Example
Must be hostnames, not URLs.	Use `example.com`, not `https://example.com/path`.
Match the hostname and subdomains.	`example.com` matches `example.com` and `docs.example.com`.
May use wildcard subdomain syntax.	`*.example.com` is accepted.
Do not support wildcard TLDs.	``, `.com`, and `example.*` are invalid.
Do not include ports.	Use origins when the port matters.

Use origins when protocol and port matter:

{ allowedOrigins: ["https://app.example.com:443"] }

Origin entries:

Rule	Example
Must include protocol, host, and port after normalization.	`https://app.example.com` normalizes to the default HTTPS port.
Match exact protocol, host, and port.	`https://app.example.com:443` does not match `http://app.example.com:80`.
Support wildcard ports only for loopback hosts.	`http://localhost:*` is valid.

Auth and redirect domains

Auth and redirect domains are not general allow-lists. They model temporary excursions from an allowed boundary.

{
  allowedDomains: ["vendor.example"],
  authDomains: ["login.vendor.example"],
  redirectDomains: ["assets.vendor-cdn.example"]
}

Field	Use it for
`authDomains`	Login, SSO, OAuth, or identity-provider hops.
`redirectDomains`	Expected non-auth redirects such as CDN, payment processor landing pages, or file-host redirects.

When content access remains on an auth domain, policy can return policy_auth_excursion_return_required to nudge the workflow back to the trusted boundary.

Private access

Private-network destinations include localhost, private IP ranges, link-local addresses, and known metadata services.

{
  allowedDomains: ["internal.example"],
  privateAccess: {
    domains: ["internal.example"],
    cidrs: ["10.0.0.0/8"],
    localhost: true
  }
}

Value	Description
`"trusted-domains"`	Allows private access for trusted policy domains.
`{ domains }`	Allows private access for listed private-access domains.
`{ cidrs }`	Allows private access for listed CIDR ranges.
`{ localhost: true }`	Allows localhost access.

Private access requires allowedDomains or allowedOrigins. Metadata endpoints remain protected by the address-space classifier unless explicitly allowed by policy and runtime controls.

Downloads, uploads, and approvals

type BrowserPolicyActionMode = "allow" | "requireApproval" | "deny";

BrowserDownloadPolicy:

Field	Type	Description
`mode`	`BrowserPolicyActionMode`	Whether downloads are allowed, approval-gated, or denied.
`maxBytes`	`number`	Maximum download size.
`blockedExtensions`	`string[]`	File extensions to block.

BrowserUploadPolicy:

Field	Type	Description
`mode`	`BrowserPolicyActionMode`	Whether uploads are allowed, approval-gated, or denied.
`maxBytes`	`number`	Maximum upload size.
`allowedMimeTypes`	`string[]`	Allowed MIME types. MIME values support exact subtypes and wildcard subtype syntax such as `image/*`.

BrowserApprovalRules:

Field	Type	Description
`destructiveActions`	`BrowserPolicyActionMode`	Default control for deterministic destructive-action classifications.

Policy tips

Policy tips are user-facing hints returned by policy-aware surfaces. A tip may include observed domains and a suggested policy patch.

Code	Meaning
`policy_auth_domain_suggested`	A navigation looks like an auth redirect that is not in `authDomains`.
`policy_redirect_domain_suggested`	A navigation looks like an expected redirect that is not in `redirectDomains`.
`policy_navigation_kept_in_scope`	Policy kept the browser inside the configured boundary.
`policy_private_access_suggested`	A private-access policy refinement may be needed.
`policy_private_network_protected`	Private-network access was protected by policy.
`policy_auth_excursion_active`	The browser is currently in an auth excursion.
`policy_auth_excursion_return_required`	Content access on an auth domain should return to an allowed domain.

Validation rules

Policy normalization rejects invalid shapes early:

Rule	Example
`mode` must be `strict` or `guided`.	`mode: "monitor"` is invalid.
Domain entries must be domains, not URLs.	`https://example.com` is invalid in `allowedDomains`.
Origins must be valid origins.	`https://example.com/path` is invalid in `allowedOrigins`.
Wildcard TLD domain patterns are not supported.	`*.com` is invalid.
`mode`, `authDomains`, `redirectDomains`, and `privateAccess` require `allowedDomains` or `allowedOrigins`.	`{ mode: "guided" }` is invalid.
Private-access domains and CIDRs must be valid.	Invalid CIDR strings are rejected.

Policy is not a prompt

Policy is enforced by Webcompute surfaces that accept policy. It is not a substitute for:

App-level authorization.
Human approval for irreversible business actions.
Careful secret scoping.
Proxy credential handling.
Reviewing generated browser code before using it in higher-risk workflows.

For approval-sensitive agent workflows, combine browser policy with approval: "ask" and an onConfirm callback.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

Where policy is accepted

`BrowserNavigationPolicy`

Modes

Domains and origins

Auth and redirect domains

Private access

Downloads, uploads, and approvals

Policy tips

Validation rules

Policy is not a prompt

​Where policy is accepted

​BrowserNavigationPolicy

​Modes

​Domains and origins

​Auth and redirect domains

​Private access

​Downloads, uploads, and approvals

​Policy tips

​Validation rules

​Policy is not a prompt

Where policy is accepted

`BrowserNavigationPolicy`

Modes

Domains and origins

Auth and redirect domains

Private access

Downloads, uploads, and approvals

Policy tips

Validation rules

Policy is not a prompt