# Hosting Steel Browser

Run a browser automation API inside a Sandbox0 sandbox when you want CDP, browser profile state, cookies, downloads, and a live browser view behind Sandbox0 lifecycle and public ingress.

The builtin `browser` template uses the upstream Steel Browser image. It stores Chrome profile data under `/browser/profile` and downloads under `/files` on the sandbox writable rootfs.

## Create The Service

Claim the builtin `browser` template and expose Steel Browser as a `cmd` Sandbox Service. The service command runs the Steel image entrypoint directly; no wrapper image or script is required.

```json
{
    "id": "browser",
    "display_name": "Steel Browser",
    "port": 3000,
    "runtime": {
        "type": "cmd",
        "command": [
            "sh",
            "-lc",
            "set -eu\nexport PORT=\"${SANDBOX0_SERVICE_PORT}\"\nexport HOST=\"0.0.0.0\"\nif [ -n \"${SANDBOX0_APP_DOMAIN:-}\" ]; then\n    export DOMAIN=\"${SANDBOX0_SANDBOX_ID}--p${SANDBOX0_SERVICE_PORT}.${SANDBOX0_APP_DOMAIN}\"\n    export USE_SSL=true\nfi\nexec /app/api/entrypoint.sh --no-nginx"
        ]
    },
    "ingress": {
        "public": true,
        "routes": [
            {
                "id": "api",
                "path_prefix": "/",
                "rewrite_prefix": "/",
                "timeout_seconds": 300,
                "resume": true,
                "auth": {
                    "mode": "bearer",
                    "bearer_token_sha256": "<sha256-of-route-token>"
                }
            }
        ]
    },
    "health_check": {
        "path": "/v1/health"
    }
}
```

`SANDBOX0_SANDBOX_ID`, `SANDBOX0_APP_DOMAIN`, and `SANDBOX0_SERVICE_PORT` are injected by Sandbox0. Steel uses `DOMAIN` and `USE_SSL=true` to return public `https` and `wss` URLs in session responses.

## Use Steel Browser

After the sandbox is claimed, list the sandbox services and use the `public_url` for the `browser` service as the Steel base URL.

```bash
export BROWSER_BASE_URL="https://<sandbox-id>--p3000.<region>.<root-domain>"
export BROWSER_ROUTE_TOKEN="<route-token>"

curl -sS "$BROWSER_BASE_URL/v1/sessions" \
    -H "Authorization: Bearer $BROWSER_ROUTE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'
```

The session response includes `websocketUrl` for CDP clients, `debugUrl` for the live browser view, `debuggerUrl` for DevTools, and `sessionViewerUrl` for the Steel session viewer.

When route auth is enabled, CDP and WebSocket clients must send the configured auth header. For human live-view access in a normal browser, open `debugUrl` through a protected frontend that can authenticate the route, or use a route auth mode that matches your access boundary.

Steel Browser automation clients can connect to `websocketUrl` with Playwright or a CDP client:

```js
import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.websocketUrl, {
    headers: { Authorization: `Bearer ${process.env.BROWSER_ROUTE_TOKEN}` },
});
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");
```

## Persistence

Chrome profile data, cookies, local storage, extension state, downloads, and file exchange live on the sandbox rootfs. Pause/resume preserves them for the same sandbox identity. Create a named rootfs snapshot when you need a reusable restore point or an isolated copy in another sandbox.

Do not pass Steel `persist` or `userDataDir` session options unless you intentionally want to override the template's `CHROME_USER_DATA_DIR`.

The default filesystem-only pause restarts Steel and Chromium after resume.
Explicit experimental [memory pause/resume](/docs/sandbox/pause-resume#explicit-memory-pause-and-resume)
can retain supported process state, but CDP and other external clients must
reconnect. Runtime requests are routed to a committed generation and may wait
while lifecycle transactions commit.

## Capabilities

The browser API is provided by Steel Browser and Chromium inside the image:

| Capability | Path |
|------------|------|
| CDP | Steel returns `websocketUrl` from `/v1/sessions` |
| Extensions | Pass extension options through the Steel session API |
| Profiles and cookies | Chrome user data directory at `/browser/profile` |
| Downloads and files | Steel file service path `/files` |
| Live view | Steel `debugUrl`, `sessionViewerUrl`, and cast WebSocket routes |

Platform administrators manage a public `browser` template through the normal
template API with a system identity. Self-hosted teams can instead create a
private template that pins a reviewed Steel Browser digest. Warm capacity comes
from the shared resource-neutral carrier pool and is not configured on this
template.

## Next Steps

<CardGroup>
  <Card title="Use Cases" href="/docs/sandbox/use-cases" cta="Back">
    Compare Steel Browser with the other Sandbox0-hosted use cases.
  </Card>

  <Card title="Sandbox Services" href="/docs/sandbox/services" cta="Continue">
    Tune route auth, resume behavior, timeouts, and public service exposure.
  </Card>

  <Card title="Snapshot And Restore" href="/docs/sandbox/snapshot-restore" cta="Continue">
    Publish initialized browser state and downloads as a rootfs snapshot.
  </Card>
</CardGroup>