> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Proxies

> Save proxy configurations and attach them to browser Runtimes.

A saved **Proxy** is a reusable traffic configuration for browser Runtimes.
Choose a custom endpoint, a managed rotating proxy, or a managed static lease.
Attach a saved Proxy through [Runtimes](/sdk/runtimes#browser-configuration).

## Choose a proxy type

| Type               | Use it for                       | Requires                               |
| ------------------ | -------------------------------- | -------------------------------------- |
| `custom`           | An endpoint you operate          | Protocol and connection details        |
| `managed-rotating` | Provider-backed rotating traffic | A provider pool and optional targeting |
| `managed-static`   | A leased static IP               | A pool ID from the managed catalog     |

## Create a custom Proxy

```ts
const proxy = await bctrl.proxies.create({
  type: "custom",
  name: "acme-residential",
  protocol: "http",
  host: "proxy.acme.com",
  port: 8080,
  username: process.env.PROXY_USER,
  password: process.env.PROXY_PASS,
});
```

`protocol` is `"http"` or `"socks5"`. You can also provide a proxy `url`
instead of separate host and port fields. `dnsResolution` can be `"local"` or
`"proxy"`; `udpMode` can be `"disabled"`, `"auto"`, or `"required"`.

## Create a managed rotating Proxy

Managed rotating Proxies use one of the provider pools. `pool1` supports
country, region, city, ISP, IP family, and preference targeting. `pool2`
supports country, state, city, and device targeting.

```ts
const rotating = await bctrl.proxies.create({
  type: "managed-rotating",
  name: "us-rotating",
  pool: "pool1",
  country: "us",
  preference: "balanced",
  rotation: "rotating",
});
```

Common rotating fields:

| Parameter                   | Type                                                    | Required | Description                                                      |
| --------------------------- | ------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `pool`                      | `"pool1" \| "pool2"`                                    | Yes      | Provider pool. The remaining fields depend on the selected pool. |
| `protocol`                  | `"http" \| "socks5"`                                    | No       | Proxy protocol.                                                  |
| `rotation`                  | `"sticky" \| "rotating"`                                | No       | Reuse or rotate the exit identity.                               |
| `stickyKey`                 | `string`                                                | No       | Key used when `rotation` is `"sticky"`.                          |
| `geoId`                     | `string`                                                | No       | Exact location returned by the catalog.                          |
| `country`                   | `string`                                                | No       | Two-letter country code.                                         |
| `region` / `state` / `city` | `string`                                                | No       | Location targeting, depending on pool.                           |
| `isp`                       | `string`                                                | No       | ISP targeting for `pool1`.                                       |
| `ipFamily`                  | `"dual-stack" \| "ipv4-only"`                           | No       | IP family for `pool1`.                                           |
| `preference`                | `"balanced" \| "speed" \| "quality" \| "coverage"`      | No       | Pool preference for `pool1`.                                     |
| `device`                    | `"windows" \| "macos" \| "linux" \| "android" \| "ios"` | No       | Device targeting for `pool2`.                                    |

## Browse managed proxy locations

Search the provider-backed geo catalog when you need an exact `geoId` for a
managed rotating Proxy:

```ts
const geo = await bctrl.proxies.geo.list({
  country: "us",
  type: "city",
  q: "new york",
});

const geoId = geo.data[0]?.geoId;
```

Use the customer-facing locations catalog to browse the locations available
for a managed pool:

```ts
const locations = await bctrl.proxies.locations.list({
  pool: "pool1",
  country: "us",
});

for (const location of locations.data) {
  console.log(location.name, location.geoId, location.pools);
}
```

Both catalog clients support `list()` and `iter()` with the same pagination
filters: `cursor`, `limit`, `q`, `country`, `region`, `type`, and `pool`.

Discover static pools before creating a managed static Proxy:

```ts
const pools = await bctrl.proxies.pools.list({
  country: "us",
  available: true,
});

const pool = await bctrl.proxies.pools.get(pools.data[0].id);
```

## Create a managed static Proxy

```ts
const leased = await bctrl.proxies.create({
  type: "managed-static",
  name: "us-residential",
  poolId: pool.id,
  autoRenew: true,
});
```

Managed static Proxies may be `provisioning`, `active`, `provisioning_failed`,
`expired`, or `renewal_failed`. The assigned IP, location, pricing, and
expiration fields become available when the lease is provisioned.

## Attach a Proxy to a Runtime

Pass the saved Proxy ID in browser Runtime configuration:

```ts
const runtime = await bctrl.runtimes.create({
  config: {
    proxy: proxy.id,
  },
});
```

The Proxy is selected when the Runtime starts. Changes to a saved Proxy apply
to future Runtime starts.

## Inspect and test a Proxy

```ts
const current = await bctrl.proxies.get(proxy.id);

const result = await bctrl.proxies.test(proxy.id);
console.log(result.ok, result.exitIp, result.country);

await bctrl.proxies.update(proxy.id, {
  name: "acme-residential-eu",
  country: "de",
});

await bctrl.proxies.delete(proxy.id);
```

Proxy credentials are write-only. Responses expose `hasPassword` for custom
Proxies rather than returning the password.

## Proxy resource fields

All Proxy responses include:

| Field          | Type                                                 | Always present | Description                        |
| -------------- | ---------------------------------------------------- | -------------- | ---------------------------------- |
| `id`           | `string`                                             | Yes            | Saved Proxy identifier.            |
| `name`         | `string`                                             | Yes            | Human-readable label.              |
| `type`         | `"custom" \| "managed-rotating" \| "managed-static"` | Yes            | Proxy kind.                        |
| `subaccountId` | `string`                                             | No             | Subaccount owner, when applicable. |
| `createdAt`    | `string`                                             | Yes            | Creation timestamp.                |
| `updatedAt`    | `string`                                             | Yes            | Last update timestamp.             |

The remaining fields depend on `type`. Custom Proxies expose connection
details and `hasPassword`; managed rotating Proxies expose their pool and
targeting configuration; managed static Proxies additionally expose lease
status and assignment details.

Use `bctrl.proxies.list()` and `iter()` to enumerate saved Proxies. Use
`bctrl.proxies.pools.list()`, `iter()`, and `get()` to browse managed pools.