Docker
Self-Hosting Steel Browser Using Docker
This guide provides step-by-step instructions to set up your own Steel Browser instance using Docker. The setup consists of two main components: an API service that manages Chrome instances and a user interface for interaction.
PrerequisitesCopied!
-
Docker (20.10.0 or later)
-
At least 4GB of RAM
-
10GB of free disk space
Quick StartCopied!
-
Create a new directory for your Steel Browser instance:
mkdir steel-browser && cd steel-browser
-
Create the following file:
docker-compose.yml
services: api: image: ghcr.io/steel-dev/steel-browser-api:latest ports: - "3000:3000" - "9223:9223" volumes: - ./.cache:/app/.cache networks: - steel-network ui: image: ghcr.io/steel-dev/steel-browser-ui:latest ports: - "5173:80" depends_on: - api networks: - steel-network networks: steel-network: name: steel-network driver: bridge
-
Launch the containers:
docker compose up -d
-
Access Steel Browser by opening
http://localhost:5173
in your web browser.
Advanced SetupCopied!
Building From Source
If you prefer to build the containers yourself:
-
Clone the repository:
git clone https://github.com/steel-dev/steel-browser.git cd steel-browser
-
Create a
.env
file (optional):API_URL=YOUR_API_URL
-
Build and start using the development compose file:
docker compose -f docker-compose.dev.yml up -d --build
The “-d” will run the containers in the background.
Configuration Options
-
API Port: Default is 3000 (also 3000 inside the container). Change in the compose file if needed
-
Heads up, changing the external facing port won’t change the fact that anything on the
steel-network
will just use internal ports — so you will also have to change the port that the api binds to, for it to be reflected in the UI
-
-
UI Port: Default is 5173 (or 80 inside container). Adjust if required
-
Chrome Debugging Port: Default is 9223. Required for browser communication
Volume Persistence
The .cache
directory stores Chrome data and extensions. Mount it as a volume for persistence:
volumes:
- ./.cache:/app/.cache
ArchitectureCopied!
Steel Browser consists of two main components:
-
API Container: Runs Chrome in headless mode, providing CDP (Chrome DevTools Protocol) services
-
UI Container: Nginx-based frontend for interacting with the browser
Customizing the BuildCopied!
Using a Different Chrome Version
The API container uses Chrome 128.0.6613.119 by default. To use a different version:
-
Create a custom Dockerfile based on the API one
-
Modify the Chrome installation section:
ARG CHROME_VERSION="128.0.6613.119"
RUN apt-get update && \
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
wget \
ca-certificates \
curl \
unzip \
&& CHROME_DEB="google-chrome-stable_${CHROME_VERSION}-1_amd64.deb" \
&& wget -q "https://mirror.cs.uchicago.edu/google-chrome/pool/main/g/google-chrome-stable/${CHROME_DEB}" \
# ...rest of the installation...
Changing Node Version
Both containers use Node 22.13.0 by default. To use a different version, modify the build arguments:
services:
api:
build:
context: .
dockerfile: ./api/Dockerfile
args:
NODE_VERSION: 18.19.0
TroubleshootingCopied!
Chrome Won't Start
Ensure your host has enough resources and check the API container logs:
docker logs steel-browser_api_1
Common issues:
-
Running on ARM architecture (solution for this coming soon!)
-
Insufficient memory
-
Missing shared libraries
-
Permission problems with
.cache
directory
Connectivity Issues
If the UI can't connect to the API:
-
Verify both containers are running:
docker-compose ps
-
Check if the API is accessible:
curl http://localhost:3000/api/health
-
Ensure the containers can communicate over the network:
docker exec steel-browser_ui_1 curl http://api:3000/api/health
Production DeploymentCopied!
For production environments:
-
Use specific image versions instead of
latest
-
Set up proper reverse proxy with HTTPS
-
Configure appropriate resource limits
Example production compose file:
services:
api:
image: ghcr.io/steel-dev/steel-browser-api:sha256:...
restart: always
ports:
- "3000:3000"
deploy:
resources:
limits:
memory: 2G
volumes:
- ./data/.cache:/app/.cache
networks:
- steel-network
ui:
image: ghcr.io/steel-dev/steel-browser-ui:sha256:...
restart: always
ports:
- "5173:80"
networks:
- steel-network
networks:
steel-network:
name: steel-network
driver: bridge
Security ConsiderationsCopied!
-
Don't expose Chrome debugging port (9223) to the public internet
-
You can also choose to not expose the API as well if you’re automations/agent also run within the same network as the
ui
andapi
containers
-
-
Set up proper authentication if deploying publicly
-
Keep containers updated with the latest versions
UpdatingCopied!
To update to the latest version:
docker compose pull
docker compose up -d
For custom builds:
git pull
docker compose -f docker-compose.dev.yml up -d --build
Now your Steel Browser instance is up and running on your own infrastructure!