Skip to main content
Production browser jobs need two separate boundaries:
  • Policy controls what the browser is allowed to do.
  • Proxy controls the network path used by browser traffic.
Use both when the job has a known target and a required egress route. Do not treat either one as permission to access a site, bypass a blocker, or ignore site rules.

​
Support matrix

NeedSupported surfacesNotes
Full browser policySDK browser creation, SDK agent browser creation, SDK quick actions, REST browser creation, REST quick actions, MCP manage_browsers createUse BrowserNavigationPolicy fields such as allowedDomains, authDomains, downloads, uploads, and approvals.
CLI agent domain boundaryweb agent --allow-domain <domain>The CLI agent exposes domain allow-listing, not the full policy object.
MCP server startup policyweb mcp run --allow-domain, --allow-origin, --private-access localhostApplies to browsers the MCP runtime creates.
Custom proxySDK browser creation, SDK agent browser creation, SDK quick actions, CLI browser creation, CLI quick actions, REST browser creation, REST quick actionsKeep proxy URLs in environment variables.
MCP custom proxyNot currently exposedCurrent MCP tool schemas do not include a browser-create proxy field.
CLI web agent custom proxyNot currently exposedUse SDK web.agent({ browser: { create: { proxy } } }) when delegated agent work needs a custom proxy.

​
SDK browser job

import { Web } from "@webcompute/sdk";

const web = new Web();

const browser = await web.browser.create({
  proxy: process.env.RESIDENTIAL_PROXY_URL,
  recording: true,
  policy: {
    mode: "strict",
    allowedDomains: ["vendor.example"],
    authDomains: ["login.vendor.example"],
    downloads: { mode: "requireApproval", maxBytes: 25_000_000 },
    uploads: { mode: "deny" },
    approvals: { destructiveActions: "requireApproval" },
  },
});

try {
  const result = await browser.playwright.execute({
    code: `
      await page.goto("https://vendor.example/account");
      return { title: await page.title(), url: page.url() };
    `,
    capture: { status: true, observation: { kind: "aria", includeOn: "always" } },
  });

  console.log(result.result);
} finally {
  await browser.close();
}
In deterministic browser control, your code owns the target, extraction, validation, and cleanup.

​
SDK agent job

const agent = web.agent({
  model,
  browser: {
    create: {
      proxy: process.env.RESIDENTIAL_PROXY_URL,
      recording: true,
      policy: { allowedDomains: ["vendor.example"] },
    },
  },
  approval: "ask",
});

const result = await agent.run({
  startUrl: "https://vendor.example",
  goal: "Review the visible account status and return the account name, plan, and renewal date.",
});
In delegated browser work, the model chooses Playwright steps inside the browser boundary you configured.

​
MCP policy

web mcp run \
  --allow-domain sec.gov \
  --private-access localhost
MCP policy is useful when a coding agent creates browsers through manage_browsers. It is not a proxy setting. If an MCP workflow needs a proxied browser, create that browser through SDK, CLI, or REST first, then reuse the browser ID where the workflow supports it.

​
Failure handling

SignalResponse
Policy denialStop or refine the policy deliberately. Do not retry with a wider policy automatically.
Proxy authentication failureRotate or correct the proxy credential outside prompts and logs.
Proxy connection failureRetry with backoff only if the job is safe to repeat.
Unexpected auth or redirect domainAdd authDomains or redirectDomains only after confirming the domain belongs to the workflow.
Upload/download policy decisionAsk for human review when the action can expose data or change state.
Reference: policy reference, proxy reference, security and secrets, and errors and retries.