***

title: Proxy
description: Route browser traffic through HTTP or SOCKS5 proxies.
------------------------------------------------------------------

Browser runtimes can route all traffic through a proxy. Use this for geo-targeting, IP rotation, or accessing region-locked content.

## Configuring a proxy

Pass a proxy configuration when launching the runtime:

```ts
const runtime = await workspace.runtimes.browser("main").playwright({
  mode: "ephemeral",
  config: {
    proxy: {
      type: "http",
      host: "proxy.example.com",
      port: 8080,
      username: "user",
      password: "pass",
    },
  },
});
```

| Parameter  | Type                 | Required | Description             |
| ---------- | -------------------- | -------- | ----------------------- |
| `type`     | `'http' \| 'socks5'` | Yes      | Proxy protocol          |
| `host`     | `string`             | Yes      | Proxy server hostname   |
| `port`     | `number`             | Yes      | Proxy server port       |
| `username` | `string`             | No       | Authentication username |
| `password` | `string`             | No       | Authentication password |

## Driver-level proxy

You can also configure proxies at the driver level using the native driver options.

### Playwright

```ts
const runtime = await workspace.runtimes.browser("main").playwright({
  mode: "ephemeral",
  driverOptions: {
    proxy: {
      server: "http://proxy.example.com:8080",
      username: "user",
      password: "pass",
      bypass: "*.internal.com",
    },
  },
});
```

| Parameter  | Type     | Required | Description                       |
| ---------- | -------- | -------- | --------------------------------- |
| `server`   | `string` | Yes      | Proxy server URL                  |
| `username` | `string` | No       | Authentication username           |
| `password` | `string` | No       | Authentication password           |
| `bypass`   | `string` | No       | Comma-separated domains to bypass |

### Puppeteer

```ts
const runtime = await workspace.runtimes.browser("main").puppeteer({
  mode: "ephemeral",
  driverOptions: {
    proxyServer: "http://proxy.example.com:8080",
    proxyBypassList: ["*.internal.com"],
  },
});
```

| Parameter         | Type       | Required | Description                         |
| ----------------- | ---------- | -------- | ----------------------------------- |
| `proxyServer`     | `string`   | No       | Proxy server URL with optional port |
| `proxyBypassList` | `string[]` | No       | Hosts to bypass the proxy for       |

## Proxy with authentication from vault

Store proxy credentials in the vault and reference them at launch:

```ts
// Store proxy credentials
await bctrl.vault.set("prod/proxy/residential", {
  username: "user",
  password: "pass",
  origins: ["*"],
});

// Use vault credentials
const runtime = await workspace.runtimes.browser("main").playwright({
  mode: "ephemeral",
  config: {
    proxy: {
      type: "http",
      host: "residential.proxy.com",
      port: 9090,
      username: "user",
      password: "pass",
    },
  },
});
```

## No proxy

Pass `null` to explicitly disable proxying:

```ts
config: {
  proxy: null,
}
```