Configuration
Environment variables control where a self-hosted Steel Browser server listens, how it starts Chrome, what it logs, and whether it serves the Commands API. Session options choose the extensions that a session loads and where it keeps browser data. Your instance's OpenAPI documentation, at /documentation, lists every session option.
Environment variables
Set a variable with -e on docker run, as in Enable the Commands API, or under environment: of the api service in a Docker Compose file. A .env file next to the compose file only fills the ${...} values in it, such as ${DOMAIN}. Docker Compose does not pass the file to the container. When you run the server from source, it reads a .env file from the folder that you start it in.
A variable of the type "flag" is on when its value is true or 1.
Server and URLs
| Variable | Type | Default | Meaning |
|---|---|---|---|
NODE_ENV | test, development, staging, production or preview | development. The Docker image sets production. | With production, the server serves the UI at /. With development, it keeps session files in the system's temporary folder instead of /, and it prints readable logs. |
HOST | text | 0.0.0.0 | The IP address that the server listens on. Chrome accepts debugger connections on the same address. |
PORT | number | 3000 | The port that the API listens on. |
DOMAIN | text | none | The host, and the port if needed, in the URLs that the server returns, such as websocketUrl and sessionViewerUrl. Without it, the server writes HOST:PORT, with localhost instead of 0.0.0.0. Set it when the server runs behind a domain or a proxy. |
USE_SSL | flag | false | When on, the URLs that the server returns start with https:// and wss://. Turn it on behind HTTPS. |
CDP_DOMAIN | text | DOMAIN | The host in the debugger URLs. |
CDP_REDIRECT_PORT | number | 9222. The Docker image sets 9223. | The port in the debugger URLs when CDP_DOMAIN and DOMAIN are not set. |
ENABLE_COMMANDS_API | flag | false | Turn on the Commands API. See Enable the Commands API. |
KILL_TIMEOUT | number | 0 | Read but not used. |
Chrome
| Variable | Type | Default | Meaning |
|---|---|---|---|
CHROME_EXECUTABLE_PATH | path | Chrome's usual path on the system | The Chrome program to start. Set it when Chrome is somewhere else. |
CHROME_HEADLESS | flag | true | Run Chrome without a window. The session option headless overrides it for one session. |
DISPLAY | text | :10 | The X display for Chrome when it runs with a window. |
CHROME_ARGS | text | none | Extra command-line arguments for Chrome, separated by spaces. |
FILTER_CHROME_ARGS | text | none | Arguments to remove from the Chrome command line, separated by spaces. |
DISABLE_CHROME_SANDBOX | flag | false | Start Chrome without its sandbox. The server also does this when it runs as root. |
DEBUG_CHROME_PROCESS | flag | false | Print the Chrome process's output and errors. |
CHROME_USER_DATA_DIR | path | steel-chrome in the system's temporary folder | The Chrome data folder for a session without persist. |
CONTEXT_CACHE_TTL_MS | number | 1000 | How long, in milliseconds, the server reuses the cookies and storage that it read from the Chrome data folder. |
DEFAULT_HEADERS | JSON object | {} | HTTP headers that the browser adds to every request from every page, such as {"X-Team":"qa"}. |
DEFAULT_TIMEZONE | time zone name | the host's time zone | The browser's time zone when the session sets none and the time zone service returns none. |
TIMEZONE_SERVICE_URL | URL | https:// | The service that the server asks for the time zone of the browser's IP address, through the session's proxy. It reads the timezone field of the JSON response. |
SKIP_FINGERPRINT_INJECTION | flag | false | Turn off fingerprint injection for every session. The session option skipFingerprintInjection turns it off for one session. |
PROXY_INTERNAL_BYPASS | text | none | Hosts that skip the session's proxy, separated by commas. 0.0.0.0 and HOST always skip it. |
PROXY_URL | text | none | Read but not used. Pass a proxy for each session with proxyUrl. |
Logging
| Variable | Type | Default | Meaning |
|---|---|---|---|
LOG_LEVEL | debug, info, warn or another Pino level | debug | The log level with NODE_ENV=development. |
ENABLE_VERBOSE_LOGGING | flag | false | With NODE_ENV=development, adds each log call's arguments to the log line. |
LOG_STORAGE_ENABLED | flag | false | Store browser logs in a DuckDB file. The Docker Compose file turns it on. |
LOG_STORAGE_PATH | path | steel-browser-logs/ in the system's temporary folder | The DuckDB file for browser logs. |
ENABLE_CDP_LOGGING | flag | false | Read but not used. |
LOG_CUSTOM_EMIT_EVENTS | flag | false | Read but not used. |
Docker image and UI
| Variable | Type | Default | Meaning |
|---|---|---|---|
DEBUG | true | none | In the Docker image, start DBus, check Chrome and ChromeDriver, and print each step of the startup. |
API_URL | URL | http:// in the Docker Compose files | In the UI container, the URL of the API that the UI sends its requests to. |
VITE_API_URL | URL | /. The single Docker image builds the UI with an empty value. | When you build the UI, the URL prefix of each API request that the UI sends. In the UI container, nginx forwards / to API_URL. |
VITE_WS_URL | URL | /. The single Docker image builds the UI with an empty value. | When you build the UI, the URL prefix of each WebSocket connection that the UI opens. In the UI container, nginx forwards / to API_URL. |
The repository's .env.example sets DOMAIN=localhost:3000, CDP_DOMAIN=localhost:9223 and API_URL=http://api:3000, the three values that its compose file reads. Copy it to .env and change the hosts when you reach the server through another host name.
Chrome always listens for debugger connections on port 9222. In the Docker image, nginx forwards port 9223 to it, and the start script sets CDP_REDIRECT_PORT=9223 and DISPLAY=:10, whatever values you pass for these two. To start the image without nginx, pass --no-nginx to the start script, after the image name in docker run.
Enable the Commands API
The Commands API drives a session with commands, as on Steel Cloud. See Commands. In Steel Browser it is Experimental and off by default. Without ENABLE_COMMANDS_API, its routes do not exist.
Start the server with the variable on:
docker run --rm -p 127.0.0.1:3000:3000 -p 127.0.0.1:9223:9223 \
-e ENABLE_COMMANDS_API=true \
ghcr.io/steel-dev/steel-browser:latestWith Docker Compose, add ENABLE_COMMANDS_API=true under environment: of the api service.
The server then has these routes:
| Method | Path | Meaning |
|---|---|---|
POST | / | Run commands in the session. |
GET | / | Get an execution. The server waits up to 20 seconds for it to finish. |
POST | / | Cancel an execution. Commands that already ran are not undone. |
GET | / | The JSON Schema of the request body. |
sessionId must be the session that the server runs. A request for another session gets 410 with the code session_ended.
steel dev start, in the Steel CLI, runs the repository's Docker Compose file from ~/.config/steel/steel-browser, and it does not turn on the Commands API. To use the steel browser commands with this instance, add ENABLE_COMMANDS_API=true under environment: of the api service in that folder's docker-compose.yml, and restart the instance. That compose file also publishes its ports on all network interfaces. Run with Docker shows how to keep them on your machine.
Commands reference lists the commands.
Extensions and profiles
Steel Browser has no Extensions API and no Profiles API. It loads extensions from a folder, and it keeps browser data in a folder. You choose both when you create a session.
| Setting | Where | Meaning |
|---|---|---|
api/ | A folder in the repository | Holds one folder for each unpacked Chrome extension. The Docker image copies the folder at build time, so add your extension and build the image from source. |
extensions | Session option, a list of names | The extension folders to load into the session. A name without a folder in api/ is skipped. |
persist | Session option, true or false | With true, Chrome uses the server's api/ folder, so cookies and storage stay from one session to the next. |
userDataDir | Session option, text | A value that is not empty has the same effect as persist: true. Chrome uses api/, not the path that you pass. |
CHROME_USER_DATA_DIR | Environment variable | The Chrome data folder for a session without persist or userDataDir. |
In headless mode, the server also loads its own recorder extension.
This request creates a session that loads the extension in api/extensions/my-extension and keeps its browser data:
curl -X POST http://localhost:3000/v1/sessions \
-H "Content-Type: application/json" \
-d '{"extensions": ["my-extension"], "persist": true}'In the Docker image, the server's code is in /app/api, so the data folder is /app/api/user-data-dir. It is inside the container, and it is gone when the container is removed. Mount a volume there to keep it.