Skip to content

Configuration

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 →

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

VariableTypeDefaultMeaning
NODE_ENVtest, development, staging, production or previewdevelopment. The Docker image sets production.With production, the server serves the UI at /ui. With development, it keeps session files in the system's temporary folder instead of /files, and it prints readable logs.
HOSTtext0.0.0.0The IP address that the server listens on. Chrome accepts debugger connections on the same address.
PORTnumber3000The port that the API listens on.
DOMAINtextnoneThe 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_SSLflagfalseWhen on, the URLs that the server returns start with https:// and wss://. Turn it on behind HTTPS.
CDP_DOMAINtextDOMAINThe host in the debugger URLs.
CDP_REDIRECT_PORTnumber9222. The Docker image sets 9223.The port in the debugger URLs when CDP_DOMAIN and DOMAIN are not set.
ENABLE_COMMANDS_APIflagfalseTurn on the Commands API. See Enable the Commands API.
KILL_TIMEOUTnumber0Read but not used.

Chrome

VariableTypeDefaultMeaning
CHROME_EXECUTABLE_PATHpathChrome's usual path on the systemThe Chrome program to start. Set it when Chrome is somewhere else.
CHROME_HEADLESSflagtrueRun Chrome without a window. The session option headless overrides it for one session.
DISPLAYtext:10The X display for Chrome when it runs with a window.
CHROME_ARGStextnoneExtra command-line arguments for Chrome, separated by spaces.
FILTER_CHROME_ARGStextnoneArguments to remove from the Chrome command line, separated by spaces.
DISABLE_CHROME_SANDBOXflagfalseStart Chrome without its sandbox. The server also does this when it runs as root.
DEBUG_CHROME_PROCESSflagfalsePrint the Chrome process's output and errors.
CHROME_USER_DATA_DIRpathsteel-chrome in the system's temporary folderThe Chrome data folder for a session without persist.
CONTEXT_CACHE_TTL_MSnumber1000How long, in milliseconds, the server reuses the cookies and storage that it read from the Chrome data folder.
DEFAULT_HEADERSJSON object{}HTTP headers that the browser adds to every request from every page, such as {"X-Team":"qa"}.
DEFAULT_TIMEZONEtime zone namethe host's time zoneThe browser's time zone when the session sets none and the time zone service returns none.
TIMEZONE_SERVICE_URLURLhttps://ipinfo.io/jsonThe 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_INJECTIONflagfalseTurn off fingerprint injection for every session. The session option skipFingerprintInjection turns it off for one session.
PROXY_INTERNAL_BYPASStextnoneHosts that skip the session's proxy, separated by commas. 0.0.0.0 and HOST always skip it.
PROXY_URLtextnoneRead but not used. Pass a proxy for each session with proxyUrl.

Logging

VariableTypeDefaultMeaning
LOG_LEVELdebug, info, warn or another Pino leveldebugThe log level with NODE_ENV=development.
ENABLE_VERBOSE_LOGGINGflagfalseWith NODE_ENV=development, adds each log call's arguments to the log line.
LOG_STORAGE_ENABLEDflagfalseStore browser logs in a DuckDB file. The Docker Compose file turns it on.
LOG_STORAGE_PATHpathsteel-browser-logs/logs.duckdb in the system's temporary folderThe DuckDB file for browser logs.
ENABLE_CDP_LOGGINGflagfalseRead but not used.
LOG_CUSTOM_EMIT_EVENTSflagfalseRead but not used.

Docker image and UI

VariableTypeDefaultMeaning
DEBUGtruenoneIn the Docker image, start DBus, check Chrome and ChromeDriver, and print each step of the startup.
API_URLURLhttp://api:3000 in the Docker Compose filesIn the UI container, the URL of the API that the UI sends its requests to.
VITE_API_URLURL/api. 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 /api/ to API_URL.
VITE_WS_URLURL/ws. 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 /ws/ 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:latest

With Docker Compose, add ENABLE_COMMANDS_API=true under environment: of the api service.

The server then has these routes:

MethodPathMeaning
POST/v1/sessions/{sessionId}/commandsRun commands in the session.
GET/v1/sessions/{sessionId}/commands/executions/{executionId}Get an execution. The server waits up to 20 seconds for it to finish.
POST/v1/sessions/{sessionId}/commands/executions/{executionId}/cancelCancel an execution. Commands that already ran are not undone.
GET/v1/sessions/{sessionId}/commands/schemaThe 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.

SettingWhereMeaning
api/extensions/A folder in the repositoryHolds 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.
extensionsSession option, a list of namesThe extension folders to load into the session. A name without a folder in api/extensions/ is skipped.
persistSession option, true or falseWith true, Chrome uses the server's api/user-data-dir folder, so cookies and storage stay from one session to the next.
userDataDirSession option, textA value that is not empty has the same effect as persist: true. Chrome uses api/user-data-dir, not the path that you pass.
CHROME_USER_DATA_DIREnvironment variableThe 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.