CLI Reference

browser-gateway provides a command-line interface for running and managing the gateway, and for driving a browser from the terminal.

Requires Node.js 20.17 or newer.

Commands

serve

Start the gateway server.

browser-gateway serve [options]

Without --config, the gateway uses the first file it finds: BG_CONFIG_PATH, then $BG_DATA_DIR/gateway.yml, then ./gateway.yml. A gateway.yml in the data directory therefore wins over one in the current directory. See Config File Location.

To turn the dashboard off, set dashboard.enabled: false in gateway.yml.

Examples:

# Start with default config
browser-gateway serve

# Custom config and port
browser-gateway serve --config /etc/browser-gateway/gateway.yml --port 8080

# With auth
BG_TOKEN=secret browser-gateway serve

check

Test connectivity to all configured providers. Useful for verifying your config.

browser-gateway check [--config <path>]

Output:

Provider Connectivity Check

  primary                 OK    340ms
  fallback-playwright     OK    12ms
  backup-chrome           FAIL  connection refused

3 provider(s) checked

Exit codes:

• 0 - All providers reachable
• 1 - One or more providers unreachable

mcp

Start an MCP server over stdio so an AI agent (Claude Code, Cursor, Codex and others) can drive browsers through the gateway.

browser-gateway mcp [options]

With no options, the server starts a local Chrome the first time the agent asks for a browser. A running gateway also serves MCP over HTTP at POST /mcp. See MCP for client setup.

browse

Drive a browser from the terminal, one command at a time. The browser stays open between commands, so an agent or a shell script can open a page, read it, click and type across several calls.

browser-gateway browse <verb> [args] [flags]

browser-gateway login --endpoint ws://localhost:9500 --token $BG_TOKEN
browser-gateway browse open https://en.wikipedia.org/wiki/Web_browser
browser-gateway browse fill @e5 "headless browser"
browser-gateway browse extract --format text
browser-gateway browse close

--endpoint accepts a gateway base URL (the CLI adds /v1/connect), a full /v1/connect URL, or a browser's own /devtools/ URL.

login

Save an endpoint and token for browse, after checking the endpoint answers.

browser-gateway login --endpoint <url> [--token <token>]

The values are written to ~/.browser-gateway/credentials.json, readable only by your user. BG_ENDPOINT and BG_TOKEN can stand in for the flags.

logout

Delete the saved endpoint and token.

browser-gateway logout

whoami

Show the endpoint and masked token browse will use, and whether the endpoint is reachable.

browser-gateway whoami

skills

Install an Agent Skill that teaches coding agents how to use browse.

browser-gateway skills [--dir <path>]

Without --dir, the skill is written to ~/.claude/skills/browser-gateway/SKILL.md and ~/.codex/skills/browser-gateway/SKILL.md for whichever of those tools is installed. If neither is found, the skill is printed to the terminal.

version

Print the installed version.

browser-gateway version

help

Show usage information.

browser-gateway help

Running Without Global Install

# Using npx
npx browser-gateway serve

# Using project dependency
npx browser-gateway serve --config ./gateway.yml

Environment Variables

Which interface the gateway listens on

An interface is the network address the gateway answers on. 0.0.0.0 means every address the machine has, so other machines on the network can reach it. 127.0.0.1 (also called loopback) means only programs on the same machine can.

If BG_TOKEN is not set, the /v1/* routes have no authentication, so the gateway binds to 127.0.0.1 and stays private to the machine it runs on. Set BG_TOKEN and it binds to 0.0.0.0 instead. Setting HOST yourself always wins, so HOST=0.0.0.0 still opens an unauthenticated gateway if that is what you want.

If the gateway used to be reachable from another machine and now is not, set BG_TOKEN (recommended) or set HOST=0.0.0.0 explicitly.

Graceful Shutdown

The gateway handles shutdown signals gracefully so active browser sessions aren't interrupted mid-task:

• SIGINT (Ctrl+C). Graceful shutdown
• SIGTERM. Graceful shutdown (used by Docker, systemd, Kubernetes)

What happens when the gateway receives a shutdown signal:

1. Stop accepting new connections, new requests get 503 Service Unavailable
2. Drain active sessions, wait for existing browser sessions to finish naturally
3. Timeout, after shutdownDrainMs (default: 30 seconds), force-close any remaining sessions
4. Exit, process exits cleanly

Why this matters

Browser sessions have state. If you're halfway through filling a form or scraping a page, an abrupt disconnect means lost work. Graceful shutdown gives active sessions time to finish.

Configuration

gateway:
  shutdownDrainMs: 30000    # Wait up to 30s for sessions to finish (default)

Increase this if your browser sessions are long-running (e.g., complex scraping workflows). Decrease it if you need faster restarts.

Docker and Kubernetes

Docker sends SIGTERM on docker stop, then waits 10 seconds before SIGKILL. If your shutdownDrainMs is longer than Docker's stop timeout, increase Docker's timeout:

docker stop --time 60 browser-gateway

Or in Docker Compose:

services:
  browser-gateway:
    stop_grace_period: 60s

For Kubernetes, set terminationGracePeriodSeconds to match your drain timeout.

Webhook notification

If webhooks are configured, the gateway sends a shutdown.start event when it begins shutting down.