> ## Documentation Index > Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt > Use this file to discover all available pages before exploring further. # Policy reference > Reference Webcompute browser policy fields, validation rules, tips, private-access controls, downloads, uploads, and approvals. 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. ```ts theme={null} 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 ` 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` ```ts theme={null} 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](#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: ```ts theme={null} { 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: ```ts theme={null} { 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. ```ts theme={null} { 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. ```ts theme={null} { 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 ```ts theme={null} 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.