> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driver.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxies

> Sessions egress from Driver's ISP networks by default. proxyUrl routes through your own SOCKS5 endpoint, or one of your dedicated IPs.

Traffic leaves from an ISP connection in the requested country by default. Set `proxyUrl` when you need a specific egress: your own provider, a sticky IP, or one of your dedicated addresses.

<CodeGroup>
  ```json Request theme={"dark"}
  { "proxyUrl": "socks5://user:pass@proxy.example.com:1080" }
  ```

  ```typescript TypeScript theme={"dark"}
  const session = await createSession({ proxyUrl: "socks5://user:pass@proxy.example.com:1080" });
  ```

  ```python Python theme={"dark"}
  session = create_session(proxyUrl="socks5://user:pass@proxy.example.com:1080")
  ```
</CodeGroup>

## Accepted URLs

| Scheme                                | Notes                                                                                           |
| ------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `socks5://user:pass@host:port`        | DNS resolved on the session's machine.                                                          |
| `socks5h://user:pass@host:port`       | DNS resolved through the proxy. Use it when the proxy's location should decide DNS answers too. |
| `dedicated://<ip>`, `dedicated://any` | One of the workspace's [dedicated IPs](#dedicated-ips). No credentials: Driver holds them.      |

The proxy must be reachable from Driver's machines. HTTP proxies aren't supported.

## Location coherence

Given a SOCKS URL and no `timezone` or `language`, Driver geolocates the proxy's exit before launch and derives the session's country and timezone from it. The browser won't claim New York while its packets come from Frankfurt. A `country` you also pass must match the exit, or the request is a `400`.

## Canada

Hosted sessions in Canada without a proxy egress from Driver's Canadian ISP network. Nothing to configure.

## If the proxy cannot be reached

Driver connects through the proxy before launch to find its exit. A proxy that doesn't answer is a `400`: `Could not determine SOCKS5 proxy egress location; verify the proxy or specify both timezone and language.` Passing both `timezone` and `language` skips the lookup; the session then starts even with a dead proxy, and pages fail to load inside it. An `http://` URL is rejected outright.

Credentials travel in the create request only. They aren't stored on the session record.

## Dedicated IPs

A dedicated IP is a public address reserved to your workspace: no other customer can reserve or pin it, and your sessions can ask for it by address. Reserve
them under **Browsers → Network** in the [dashboard](https://app.driver.dev/network): pick a country and a
quantity, up to however many that country has free. The pool is 100 United States and 100 Canadian addresses.
\$5 per address per month, billed on your card as a subscription line. Adding an address mid-month is charged right away, prorated to your billing date.

You never see the SOCKS5 URL behind an address. On session create, name the address:

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.driver.dev/v1/browser/session \
    -H "Authorization: Bearer $DRIVER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "proxyUrl": "dedicated://65.86.104.7" }'
  ```

  ```typescript TypeScript theme={"dark"}
  // a specific address, or any of yours, optionally in one country
  const session = await createSession({ proxyUrl: "dedicated://65.86.104.7" });
  const anyUs = await createSession({ proxyUrl: "dedicated://any~country-US" });
  ```

  ```python Python theme={"dark"}
  session = create_session(proxyUrl="dedicated://65.86.104.7")
  any_us = create_session(proxyUrl="dedicated://any~country-US")
  ```
</CodeGroup>

| Spec                         | Meaning                                |
| ---------------------------- | -------------------------------------- |
| `dedicated://<ip>`           | This address.                          |
| `dedicated://any`            | Any address you own, chosen at random. |
| `dedicated://any~country-US` | Any of yours in that country.          |

The address decides the session's `country` and `timezone`. Leave them out; a `country` you pass has to match.

`GET /v1/network/ips` lists your addresses with country, city, network type, label and status. Copy an
address from there, or from the Network page.

| Status | Code                     | Meaning                                                                   |
| ------ | ------------------------ | ------------------------------------------------------------------------- |
| `400`  | `invalid_spec`           | Not one of the forms above, or a `country` that contradicts the address.  |
| `403`  | `dedicated_ip_not_owned` | The address belongs to another workspace, or the key isn't linked to one. |
| `404`  | `no_dedicated_ip`        | Nothing matches: no addresses, or none in that country.                   |
| `503`  | `dedicated_ip_unhealthy` | The address failed its last health check. Use another one and report it.  |

Every address has a **Renews** switch on the Network page. Switch it off and the address stays yours until the
end of the month you paid for, then leaves the workspace and goes back to the pool; the seat drops at that point.
No refund for the current month. Switch it back on before then and it renews as before. The page shows what
renews on the next billing date and what that will cost. If a renewal payment fails, the addresses keep working for 2
days while the card is retried, then they're released.