Skip to main content
Custom proxies route browser traffic through a proxy URL. Use them when a workflow needs a specific egress network, region, or enterprise proxy path. Keep proxy URLs in environment variables. Proxy URLs often contain credentials, and Webcompute redaction treats proxy-shaped values as sensitive observability data. 
export RESIDENTIAL_PROXY_URL="http://user:password@proxy.example:8080"

​
Support matrix

SurfaceProxy supportHow
TypeScript SDK browser creationSupportedweb.browser.create({ proxy })
TypeScript SDK agent browser creationSupportedweb.agent({ browser: { create: { proxy } } })
TypeScript SDK quick actionsSupportedweb.scrape({ proxy }), web.screenshot({ proxy }), web.pdf({ proxy })
CLI browser creationSupportedweb browser create --proxy "$RESIDENTIAL_PROXY_URL"
CLI quick actionsSupportedweb scrape https://example.com --proxy "$RESIDENTIAL_PROXY_URL", web screenshot https://example.com --proxy "$RESIDENTIAL_PROXY_URL", web pdf https://example.com/report --proxy "$RESIDENTIAL_PROXY_URL"
REST/OpenAPI browser creationSupportedproxy field on browser-create request body.
REST/OpenAPI quick actionsSupportedproxy field on quick-action request bodies.
CLI web agentNot currently exposedThere is no web agent --proxy flag. Use the SDK agent browser-create path.
MCP runtime toolsNot currently exposedmanage_browsers does not include a proxy field in its current tool schema.
MCP run_web_agentNot currently exposedThe current tool schema accepts allowedDomains, not browser-create proxy options.

​
TypeScript SDK

​
Browser creation

const browser = await web.browser.create({
  proxy: process.env.RESIDENTIAL_PROXY_URL,
  policy: { allowedDomains: ["vendor.example"] },
});

​
Agent browser creation

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

const result = await agent.run({
  startUrl: "https://vendor.example",
  goal: "Check the current account status and return the visible account name.",
});
This is the supported SDK path for agent work that needs a custom proxy.

​
Quick actions

await web.scrape({
  url: "https://example.com",
  proxy: process.env.RESIDENTIAL_PROXY_URL,
});

await web.screenshot({
  url: "https://example.com",
  proxy: process.env.RESIDENTIAL_PROXY_URL,
});

await web.pdf({
  url: "https://example.com/report",
  proxy: process.env.RESIDENTIAL_PROXY_URL,
});
Blank proxy strings are omitted by the SDK. Non-blank values are trimmed before they are sent.

​
CLI

​
Browser creation

web browser create \
  --proxy "$RESIDENTIAL_PROXY_URL" \
  --recording

​
Quick actions

web scrape https://example.com --proxy "$RESIDENTIAL_PROXY_URL"
web screenshot https://example.com --proxy "$RESIDENTIAL_PROXY_URL" -o page.png
web pdf https://example.com/report --proxy "$RESIDENTIAL_PROXY_URL" -o report.pdf

​
Agent CLI

Current web agent does not expose a proxy flag. 
# Not supported today:
web agent --proxy "$RESIDENTIAL_PROXY_URL" "..."
Use the TypeScript SDK agent path when the agent-created browser must use a proxy.

​
REST API

The OpenAPI spec includes proxy on browser-create and quick-action request bodies. Use the REST API when you need a non-TypeScript runtime but still want direct proxy support. 
curl https://api.webcompute.dev/v1/browsers \
  -H "Authorization: Bearer $WEBCOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy":"'"$RESIDENTIAL_PROXY_URL"'"}'

​
MCP

Current MCP tool schemas do not expose a custom proxy field.
ToolCurrent proxy status
manage_browsersNo proxy argument.
execute_playwright_codeRuns against an existing browser; it does not create browser egress.
run_web_agentNo browser-create proxy argument.
If an MCP workflow needs a proxied browser, create the browser through the SDK, CLI, or REST first, then pass the browser ID to a surface that can reuse an existing browser where supported.

​
Credential handling

Proxy URLs may contain usernames, passwords, tokens, regions, or account IDs. Do:
  • Store proxy URLs in environment variables.
  • Pass proxy URLs as options, not inside natural-language prompts.
  • Avoid printing full request objects.
  • Rotate proxy credentials if a signed log or transcript leaks them.
Do not:
  • Paste proxy credentials into web agent goals.
  • Put proxy credentials in docs, examples, or issue comments.
  • Assume a proxy changes browser policy boundaries. Policy and proxy solve different problems.

​
Proxy and policy together

Proxy controls egress path. Policy controls browser scope. 
await web.browser.create({
  proxy: process.env.RESIDENTIAL_PROXY_URL,
  policy: {
    allowedDomains: ["vendor.example"],
    authDomains: ["login.vendor.example"],
  },
});
Use both for production workflows: proxy for network routing, policy for allowed browser behavior.