---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/self-hosting/configuration
markdown_url: https://steel.dev/docs/self-hosting/configuration.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Configuration
description: Configure a self-hosted Steel Browser instance with environment variables and session options, and turn on its Commands API.
summary: Configure a self-hosted Steel Browser instance with environment variables and session options, and turn on its Commands API.
type: configuration
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/docker.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Configuration

Environment variables control where a self-hosted [Steel Browser](https://steel.dev/docs/self-hosting/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](https://steel.dev/docs/self-hosting/configuration#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 `/ui`. With `development`, it keeps session files in the system's temporary folder instead of `/files`, 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](https://steel.dev/docs/self-hosting/configuration#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://ipinfo.io/json` | 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/logs.duckdb` 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://api:3000` 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 | `/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_URL` | URL | `/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](https://steel.dev/docs/control/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:

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

| Method | Path | Meaning |
| - | - | - |
| `POST` | `/v1/sessions/{sessionId}/commands` | Run 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}/cancel` | Cancel an execution. Commands that already ran are not undone. |
| `GET` | `/v1/sessions/{sessionId}/commands/schema` | 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](https://steel.dev/docs/control/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](https://steel.dev/docs/self-hosting/docker#run-the-api-and-the-ui-as-two-containers) shows how to keep them on your machine.

[Commands reference](https://steel.dev/docs/reference/commands) 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/extensions/` | 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](https://github.com/steel-dev/steel-browser). |
| `extensions` | Session option, a list of names | The extension folders to load into the session. A name without a folder in `api/extensions/` is skipped. |
| `persist` | Session option, `true` or `false` | With `true`, Chrome uses the server's `api/user-data-dir` 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/user-data-dir`, 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:

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