Run with Docker
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 playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightStart 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:latestThe 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/healthWhen 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-browserThe 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 upThe 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.
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);
}from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel(base_url="http://localhost:3000")
session = client.sessions.create()
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://example.com")
print(page.title())
browser.close()
finally:
client.sessions.release(session.id)Run the program:
npx tsx local.mtspython local.pyThe program prints the page title:
Example DomainA 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.