---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/self-hosting/docker
markdown_url: https://steel.dev/docs/self-hosting/docker.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Run with Docker
description: Start Steel Browser on your own machine or server with Docker, then create a session against your local API.
summary: Start Steel Browser on your own machine or server with Docker, then create a session against your local API.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/self-hosting/steel-browser.md
related:
  - https://steel.dev/docs/self-hosting/steel-browser.md
  - https://steel.dev/docs/self-hosting/configuration.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Run with Docker

The Docker image of [Steel Browser](https://steel.dev/docs/self-hosting/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`.

**TypeScript**

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

**Python**

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

## Start the container

Run the image from the GitHub Container Registry:

```sh
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.

> **Warning**
>
> Steel Browser does not check an API key. Anyone who can reach port `3000` or `9223` can control the browser. Do not open these ports to the internet without authentication and TLS in front of them.

Check that the API is up:

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

When the browser is up, the API returns:

```json nocopy
{"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:

```sh
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:`:

```yaml
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:

```sh
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](https://steel.dev/docs/self-hosting/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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=local.py
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:

**TypeScript**

```sh
npx tsx local.mts
```

**Python**

```sh
python local.py
```

The program prints the page title:

```text nocopy
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

- [Configuration](https://steel.dev/docs/self-hosting/configuration): Set your instance's environment variables and session options, and turn on its Commands API.
- [CLI](https://steel.dev/docs/control/cli#run-against-a-self-hosted-instance): Run `steel` commands against your instance with `--api-url` or `--local`.
