Configuration Reference

version: 1

gateway:
  port: 9500                          # Server port (default: 9500)
  defaultStrategy: priority-chain      # How the gateway chooses which provider to use
                                       # Options: priority-chain, round-robin, least-connections,
                                       #          latency-optimized, weighted
  connectionTimeout: 10000             # Max ms to wait when connecting to a provider (default: 10000)
                                       # Tip: increase to 20000-30000 for cloud providers that
                                       # launch browsers on-demand (cold start can take 10-15s)
  healthCheckInterval: 30000           # How often to check if providers are alive (default: 30000)
  shutdownDrainMs: 30000               # When stopping the gateway, how long to wait for active
                                       # sessions to finish before force-closing (default: 30000)

  cooldown:
    defaultMs: 30000                   # How long to skip a failing provider (default: 30000)
    failureThreshold: 0.5              # Cooldown when failure rate exceeds this (default: 0.5 = 50%)
    minRequestVolume: 3                # Min connection attempts before evaluating (default: 3)

  sessions:
    idleTimeoutMs: 300000              # Close sessions with no activity after this (default: 300000 = 5 min)
    reconnectTimeoutMs: 300000         # How long a disconnected session stays available for reconnection (default: 300000 = 5 min)

  queue:
    maxSize: 50                        # Max requests waiting when all providers are busy (default: 50)
    timeoutMs: 30000                   # How long a request waits in queue before giving up (default: 30000)

providers:
  provider-name:                        # Your name for this provider (any string)
    url: wss://provider.com?token=xxx  # WebSocket URL including any auth params
    headers:                           # Optional. Custom headers sent on the outbound WS upgrade
      Authorization: Bearer ${API_KEY} # Needed for providers that require an Authorization header
    limits:
      maxConcurrent: 10                # Max simultaneous connections (optional, no limit if omitted)
    priority: 1                        # Lower number = tried first (default: 1)
    weight: 1                          # For weighted strategy: higher = more traffic (default: 1)
    profile: my-profile-slug           # Optional. Only sessions using this profile come here (see Profiles)
    enabled: true                      # Optional. false keeps the provider configured but never routes to it

# Optional: get notified when things happen
webhooks:
  - url: https://hooks.slack.com/services/xxx    # Where to send notifications
    events: [provider.cooldown, queue.timeout]    # Which events (omit for all events)

dashboard:
  enabled: true                        # Enable web dashboard at /web (default: true)

logging:
  level: info                          # debug | info | warn | error (default: info)

# Saved browser profiles (see Profiles)
profiles:
  enabled: false                       # Off by default. Restart after changing
  filesystem:
    path: ./profiles                   # Resolved under $BG_DATA_DIR
  encryption:
    keyEnv: BG_ENCRYPTION_KEY          # Env var that holds the key (else $BG_DATA_DIR/.encryption-key)
  lockTtlMs: 300000                    # How long a write-back lock is held before it expires (default: 5 min)
  cdpTimeoutMs: 10000                  # Max ms to load a profile into the browser at connect
  commitTimeoutMs: 4000                # Max ms to capture and save the profile at disconnect

# Session recording storage (recording itself is per session: ?session_record=true)
replay:
  retentionDays: 7                     # Delete recordings older than this. 0 = keep forever
  maxBytesPerSession: 524288000        # 500 MB cap per session
  filesystem:
    path: ./replays                    # Resolved under $BG_DATA_DIR
  capture:
    format: jpeg                       # jpeg or png
    quality: 70                        # 1-100, jpeg only
    everyNthFrame: 1                   # 1 = every visual change

# Browser sessions used by the one-shot REST endpoints (see Session Pool below)
pool:
  minSessions: 0
  maxSessions: 5

# One-shot REST endpoints (/v1/screenshot, /v1/content, /v1/scrape)
rest:
  allowedPrivateHosts: []              # Hostnames these endpoints may reach even though they
                                       # point at a private address (default: none)

providers:
  # Cloud provider with token auth
  cloud-provider:
    url: wss://provider.example.com?token=${PROVIDER_TOKEN}

  # Self-hosted Playwright server
  my-playwright:
    url: ws://playwright-host:3000

  # Raw Chrome with remote debugging
  my-chrome:
    url: http://chrome-host:9222              # Auto-discovers WebSocket endpoint

  # Any WebSocket endpoint
  my-custom:
    url: ws://custom-service:8080/browser

limits:
  maxConcurrent: 10    # Max simultaneous connections to this provider

priority: 1    # Lower = higher priority. Tried first in priority-chain strategy.

weight: 3    # For weighted strategy only. Higher = more traffic. Default: 1.

enabled: false    # Keep the provider configured but never route to it. Default: on.

providers:
  cloud-with-bearer:
    url: wss://provider.example.com
    headers:
      Authorization: Bearer ${API_KEY}
      X-Client: browser-gateway

providers:
  provider-team-acme:
    url: wss://provider.example.com?token=${TOKEN_A}
    profile: team-acme

rest:
  allowedPrivateHosts:
    - staging.internal
    - 127.0.0.1

providers:
  production:
    url: wss://service.com?token=${API_TOKEN}

gateway:
  port: ${PORT:-9500}

# .env
BG_TOKEN=my-secret-token

version: 1

providers:
  # Cloud provider - use first
  cloud-primary:
    url: wss://provider.example.com?token=${PRIMARY_TOKEN}
    limits:
      maxConcurrent: 3
    priority: 1

  # Self-hosted servers - overflow
  playwright-1:
    url: ws://playwright-server-1:3000
    limits:
      maxConcurrent: 10
    priority: 2

  playwright-2:
    url: ws://playwright-server-2:3000
    limits:
      maxConcurrent: 10
    priority: 2

  # Second cloud provider - last resort
  cloud-backup:
    url: wss://backup-provider.example.com?key=${BACKUP_KEY}
    limits:
      maxConcurrent: 20
    priority: 3

pool:
  minSessions: 0          # Minimum browser sessions to keep alive
  maxSessions: 5           # Maximum browser connections from pool
  maxPagesPerSession: 10   # Pages per browser before creating another
  retireAfterPages: 100    # Recycle browser after this many total pages
  retireAfterMs: 3600000   # Recycle after 1 hour max
  idleTimeoutMs: 300000    # Close idle browsers after 5 minutes
  pageTimeoutMs: 30000     # Connect timeout for pool browsers