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 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.
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.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightIn Go and Rust, install only the SDK, as the Go and Rust 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.
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);
}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:
npx tsx proxy.mtspython proxy.pyThe program prints the proxy's IP address. It is not your own machine's address.
{"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.
const session = await client.sessions.create({
useProxy: { geolocation: { country: "DE" } },
});session = client.sessions.create(
use_proxy={"geolocation": {"country": "DE"}},
)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
}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, and open https://steel.dev/practice/country instead of https://steel.dev/practice/ip. The program then prints the proxy's country.
DEChoose the widest location that the task allows. A country has more addresses than a city, so its proxies fail less often. Session 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://.
http://username:password@proxy.example.com:8080const session = await client.sessions.create({
proxyUrl: process.env.PROXY_URL,
});import os
session = client.sessions.create(
proxy_url=os.environ["PROXY_URL"],
)import "os"
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
ProxyURL: steel.F(os.Getenv("PROXY_URL")),
})
if err != nil {
return err
}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.
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.
import { readFileSync } from "node:fs";
const session = await client.sessions.create({
proxyUrl: process.env.PROXY_URL,
caCertificates: [readFileSync("ca.pem", "utf8")],
});import os
from pathlib import Path
session = client.sessions.create(
proxy_url=os.environ["PROXY_URL"],
ca_certificates=[Path("ca.pem").read_text()],
)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
}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?;Check that it worked
Open https://steel.dev/practice/ip in the session, as the program in 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 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 explains. To continue without a Steel proxy, pass your own proxy in proxyUrl, or remove useProxy. Errors 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 lists the messages.
net::ERR_TUNNEL_CONNECTION_FAILED
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 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.
Verify: The page loads in the session.