Skip to content

Run with Docker

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 →

The Docker image of Steel Browser runs the browser API, Chromium and the UI in one container. Use it to develop against a browser on your own machine, or to run Steel Browser on a server that you manage. It needs no Steel account and no API key.

Before you begin

You need:

  • Docker 20.10.0 or later
  • at least 4 GB of memory and 10 GB of free disk space
  • Node.js or Python for the program on this page

Install the Steel SDK and Playwright. The program connects to the browser in the container, so you do not run playwright install.

npm install steel-sdk playwright

Start the container

Run the image from the GitHub Container Registry:

docker run --rm --name steel-browser \
  -p 127.0.0.1:3000:3000 \
  -p 127.0.0.1:9223:9223 \
  ghcr.io/steel-dev/steel-browser:latest

The API listens on port 3000, and port 9223 is for the Chrome debugger. The 127.0.0.1 in each -p makes both ports reachable only from your machine. --rm removes the container when it stops.

Check that the API is up:

curl http://localhost:3000/v1/health

When the browser is up, the API returns:

{"status":"ok"}

The UI is at http://localhost:3000/ui, and the API documentation is at http://localhost:3000/documentation.

The repository publishes the image with the tag latest only, and it builds a new one on each change to its main branch.

Run the API and the UI as two containers

The repository also has a Docker Compose file that runs the API and the UI as separate containers. It stores browser logs in a volume. Clone the repository:

git clone https://github.com/steel-dev/steel-browser.git
cd steel-browser

The compose file publishes ports 3000, 9223 and 5173 on all of the host's network interfaces. Before you start it, edit the ports lists in docker-compose.yml so that each entry starts with 127.0.0.1::

services:
  api:
    ports:
      - "127.0.0.1:3000:3000"
      - "127.0.0.1:9223:9223"
  ui:
    ports:
      - "127.0.0.1:5173:80"

Then start the containers:

docker compose up

The API is at http://localhost:3000 and the UI at http://localhost:5173. If you reach the server through another host name, for example behind a reverse proxy with authentication, copy .env.example to .env and set DOMAIN and CDP_DOMAIN to that host. Docker Compose fills them into the compose file. See Configuration.

Create a session

The Steel SDK sends requests to https://api.steel.dev by default. Point it at your instance with its base URL: baseURL in TypeScript, base_url in Python. Every Steel SDK also reads the base URL from the STEEL_BASE_URL environment variable. Then create a session and connect Playwright to its websocketUrl.

This program creates a session, opens a page, prints its title, and releases the session.

local.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel({ baseURL: "http://localhost:3000" });
const session = await client.sessions.create();

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://example.com");
  console.log(await page.title());
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx local.mts

The program prints the page title:

Example Domain

A local session's websocketUrl is ws://localhost:3000/. It has no API key in it, because Steel Browser does not need one. To watch the session while the program runs, open http://localhost:3000/ui.

Steel Browser runs one session at a time.

To stop the container, run docker stop steel-browser.

Check that it worked

Print session.websocketUrl (session.websocket_url in Python) in the program. It is ws://localhost:3000/, the address of your container, and not a wss://connect.steel.dev URL of Steel Cloud. So the session ran in your container, and the title that the program prints came from its browser.

Next steps