Proxy reference

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

Surface	Proxy support	How
TypeScript SDK browser creation	Supported	`web.browser.create({ proxy })`
TypeScript SDK agent browser creation	Supported	`web.agent({ browser: { create: { proxy } } })`
TypeScript SDK quick actions	Supported	`web.scrape({ proxy })`, `web.screenshot({ proxy })`, `web.pdf({ proxy })`
CLI browser creation	Supported	`web browser create --proxy "$RESIDENTIAL_PROXY_URL"`
CLI quick actions	Supported	`web 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 creation	Supported	`proxy` field on browser-create request body.
REST/OpenAPI quick actions	Supported	`proxy` field on quick-action request bodies.
CLI `web agent`	Not exposed	There is no `web agent --proxy` flag. Use the SDK agent browser-create path.
MCP runtime tools	Not exposed	`manage_browsers` does not include a proxy field.
MCP `run_web_agent`	Not exposed	The tool 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

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

MCP tool schemas do not expose a custom proxy field.

Tool	Proxy status
`manage_browsers`	No `proxy` argument.
`execute_playwright_code`	Runs against an existing browser; it does not create browser egress.
`run_web_agent`	No 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.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

Support matrix

TypeScript SDK

Browser creation

Agent browser creation

Quick actions

CLI

Browser creation

Quick actions

Agent CLI

REST API

MCP

Credential handling

Proxy and policy together

​Support matrix

​TypeScript SDK

​Browser creation

​Agent browser creation

​Quick actions

​CLI

​Browser creation

​Quick actions

​Agent CLI

​REST API

​MCP

​Credential handling

​Proxy and policy together

Support matrix

TypeScript SDK

Browser creation

Agent browser creation

Quick actions

CLI

Browser creation

Quick actions

Agent CLI

REST API

MCP

Credential handling

Proxy and policy together