> ## 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.

# Proxy reference

> Reference custom proxy support across SDK, CLI, REST, MCP, quick actions, browser creation, and web-agent workflows.

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.

```bash theme={null}
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

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

### Agent browser creation

```ts theme={null}
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

```ts theme={null}
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

```bash theme={null}
web browser create \
  --proxy "$RESIDENTIAL_PROXY_URL" \
  --recording
```

### Quick actions

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
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.

```ts theme={null}
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.