Skip to content

Proxies

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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 playwright

In 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.

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);
}

Run the program:

npx tsx proxy.mts

The 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" } },
});

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.

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 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:8080
const session = await client.sessions.create({
  proxyUrl: process.env.PROXY_URL,
});

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")],
});

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.

Next steps