---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/stealth/proxies
markdown_url: https://steel.dev/docs/stealth/proxies.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Proxies
description: Route a session through Steel's proxies, target a country, or bring your own proxy with the useProxy and proxyUrl options.
summary: Route a session through Steel's proxies, target a country, or bring your own proxy with the useProxy and proxyUrl options.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/stealth.md
related:
  - https://steel.dev/docs/stealth.md
  - https://steel.dev/docs/stealth/get-past-bot-detection.md
  - https://steel.dev/docs/stealth/dedicated-ips.md
  - https://steel.dev/docs/stealth/captcha-solving.md
  - https://steel.dev/docs/stealth/fingerprints.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Proxies

A session uses a datacenter IP address by default. A proxy gives the browser a different address. Use one when a site blocks datacenter addresses, or when it shows different content in different countries.

Steel proxies route a session through residential IP addresses that Steel manages. Each session gets a new address, and you pay for the bandwidth. [What each plan includes](https://steel.dev/docs/platform/pricing#what-each-plan-includes) shows which plans have them.

You can also use your own proxy, a server that you run or rent. It works on every plan, and Steel does not charge for its bandwidth.

For an address that stays the same from one session to the next, use a [dedicated IP](https://steel.dev/docs/stealth/dedicated-ips).

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable. Then install the Steel SDK and Playwright. You do not need `playwright install`, because the browser runs in Steel.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

## Use Steel proxies

Set `useProxy` to `true` when you create the session. Steel routes the browser's traffic through a residential proxy in the United States.

This program creates a session with a proxy, prints the browser's public IP address, and releases the session.

**TypeScript**

```ts file=proxy.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({ useProxy: true });

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://steel.dev/practice/ip");
  console.log(await page.textContent("body"));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=proxy.py
from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create(use_proxy=True)

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://steel.dev/practice/ip")
        print(page.text_content("body"))
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program:

**TypeScript**

```sh
npx tsx proxy.mts
```

**Python**

```sh
python proxy.py
```

The program prints the proxy's IP address. It is not your own machine's address.

```json nocopy
{"ip":"203.0.113.42"}
```

## Target a location

In `useProxy`, pass an object with `geolocation` instead of `true`. The `country` field is a two-letter country code. To narrow the location, add `state` for a state of the United States, or `city` for a city from the [list of cities](https://steel.dev/docs/reference/proxy-locations#cities).

**TypeScript**

```ts
const session = await client.sessions.create({
  useProxy: { geolocation: { country: "DE" } },
});
```

**Python**

```python
session = client.sessions.create(
    use_proxy={"geolocation": {"country": "DE"}},
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	UseProxy: steel.F[any](map[string]any{
		"geolocation": map[string]any{"country": "DE"},
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        use_proxy: Some(serde_json::json!({ "geolocation": { "country": "DE" } })),
        ..Default::default()
    })
    .await?;
```

In Rust, this code needs `cargo add serde_json`.

To check the location, put this `useProxy` value in the program from [Use Steel proxies](https://steel.dev/docs/stealth/proxies#use-steel-proxies), and open `https://steel.dev/practice/country` instead of `https://steel.dev/practice/ip`. The program then prints the proxy's country.

```text nocopy
DE
```

Choose the widest location that the task allows. A country has more addresses than a city, so its proxies fail less often. [Session configuration](https://steel.dev/docs/sessions/configuration) lists every country, state and city that you can pass.

## Bring your own proxy

Set `proxyUrl` to your proxy server's URL, with the username and password in it. The URL must start with `http://` or `https://`.

```text nocopy
http://username:password@proxy.example.com:8080
```

**TypeScript**

```ts
const session = await client.sessions.create({
  proxyUrl: process.env.PROXY_URL,
});
```

**Python**

```python
import os

session = client.sessions.create(
    proxy_url=os.environ["PROXY_URL"],
)
```

**Go**

```go
import "os"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	ProxyURL: steel.F(os.Getenv("PROXY_URL")),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        proxy_url: Some(std::env::var("PROXY_URL")?),
        ..Default::default()
    })
    .await?;
```

If a request has `proxyUrl`, Steel does not use a Steel proxy for that session, even if the request also has `useProxy`.

> **Warning**
>
> The proxy URL holds a password. Read it from an environment variable or from a secret store. Do not write it in your code.

## Trust custom CA certificates

A site with a certificate from a private certificate authority (CA) does not load, because the browser does not trust that CA. The same thing happens when your proxy inspects HTTPS traffic and signs it with its own CA.

To make the session trust a CA, pass its certificate in `caCertificates`. Each item is one certificate in PEM format.

**TypeScript**

```ts
import { readFileSync } from "node:fs";

const session = await client.sessions.create({
  proxyUrl: process.env.PROXY_URL,
  caCertificates: [readFileSync("ca.pem", "utf8")],
});
```

**Python**

```python
import os
from pathlib import Path

session = client.sessions.create(
    proxy_url=os.environ["PROXY_URL"],
    ca_certificates=[Path("ca.pem").read_text()],
)
```

**Go**

```go
import "os"

ca, err := os.ReadFile("ca.pem")
if err != nil {
	return err
}
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	ProxyURL:       steel.F(os.Getenv("PROXY_URL")),
	CaCertificates: steel.F([]string{string(ca)}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        proxy_url: Some(std::env::var("PROXY_URL")?),
        ca_certificates: Some(vec![std::fs::read_to_string("ca.pem")?]),
        ..Default::default()
    })
    .await?;
```

> **Note**
>
> `caCertificates` is Experimental. It can change without notice. See [Release stages](https://steel.dev/docs/platform/release-stages).

## Check that it worked

Open `https://steel.dev/practice/ip` in the session, as the program in [Use Steel proxies](https://steel.dev/docs/stealth/proxies#use-steel-proxies) does. It shows the address that sites see. With a proxy, that address is the proxy's, not your machine's. To check a location, open `https://steel.dev/practice/country`, which shows the country of the address.

## Plans and pricing

Steel proxies bill for the bandwidth that a session uses, in addition to its browser time. [Pricing](https://steel.dev/docs/platform/pricing) has the rate for each plan, and it explains how to verify a Launch account.

Your own proxy adds no Steel proxy charge.

## Troubleshooting

### `deposit_required`

On Launch, Steel proxies need a verified account, and a dedicated IP counts as a Steel proxy here. You verify the account once, with $10 of paid credits, as [Verify a Launch account](https://steel.dev/docs/platform/pricing#verify-a-launch-account) explains. To continue without a Steel proxy, pass your own proxy in `proxyUrl`, or remove `useProxy`. [Errors](https://steel.dev/docs/reference/errors#deposit-required) lists the messages.

### `plan_feature_unavailable`

The legacy Hobby plan does not include Steel proxies. Pass your own proxy in `proxyUrl`, remove `useProxy`, or move to a current plan. [Errors](https://steel.dev/docs/reference/errors#plan-feature-unavailable) lists the messages.

### `net::ERR_TUNNEL_CONNECTION_FAILED`

```text nocopy
page.goto: net::ERR_TUNNEL_CONNECTION_FAILED at https://example.com/
```

**Cause:** The browser did not reach the site through the proxy. The proxy's IP address stopped working, or the proxy server is down. `net::ERR_PROXY_CONNECTION_FAILED` has the same cause.

**Fix:** With a Steel proxy, release the session and create a new one. The new session gets a new address. With your own proxy, make sure that the server is up and that it accepts the username and password in `proxyUrl`.

**Verify:** Open the page again. After the session ends, its [signals](https://steel.dev/docs/observability/signals) do not include `proxy_connection_failed`.

### A site loads without a proxy, but not through a Steel proxy

**Cause:** Steel's proxy providers block some sites.

**Fix:** Target a different country with `geolocation`. If the site still does not load, use your own proxy. If you think that the site is blocked by mistake, contact [Support](https://steel.dev/docs/support).

**Verify:** The page loads in the session.

## Next steps

- [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving): Clear the challenges that a proxy does not stop.
- [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection): Find out what still blocks a session that has a proxy.
