Proxy | BCTRL | Documentation

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:

1 const runtime = await workspace.runtimes.browser("main").playwright({
2   mode: "ephemeral",
3   config: {
4     proxy: {
5       type: "http",
6       host: "proxy.example.com",
7       port: 8080,
8       username: "user",
9       password: "pass",
10     },
11   },
12 });

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

1 const runtime = await workspace.runtimes.browser("main").playwright({
2   mode: "ephemeral",
3   driverOptions: {
4     proxy: {
5       server: "http://proxy.example.com:8080",
6       username: "user",
7       password: "pass",
8       bypass: "*.internal.com",
9     },
10   },
11 });

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

1 const runtime = await workspace.runtimes.browser("main").puppeteer({
2   mode: "ephemeral",
3   driverOptions: {
4     proxyServer: "http://proxy.example.com:8080",
5     proxyBypassList: ["*.internal.com"],
6   },
7 });

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:

1 // Store proxy credentials
2 await bctrl.vault.set("prod/proxy/residential", {
3   username: "user",
4   password: "pass",
5   origins: ["*"],
6 });
7 
8 // Use vault credentials
9 const runtime = await workspace.runtimes.browser("main").playwright({
10   mode: "ephemeral",
11   config: {
12     proxy: {
13       type: "http",
14       host: "residential.proxy.com",
15       port: 9090,
16       username: "user",
17       password: "pass",
18     },
19   },
20 });

No proxy

Pass null to explicitly disable proxying:

1 config: {
2   proxy: null,
3 }