Server Management

Health checks and browser engine control

Endpoints for monitoring server health and manually controlling the browser engine lifecycle.

Health check

GET /health

Returns the current server and browser state. This endpoint is not logged to reduce noise in production logs.

Response

ok · boolean

true if server is healthy, false if recovering from errors

engine · string

Browser engine name: "camoufox"

browserConnected · boolean

true if browser is currently running and connected

browserRunning · boolean

true if browser process is active (same as browserConnected)

activeTabs · number

Total number of open tabs across all sessions

consecutiveFailures · number

Number of consecutive navigation failures. Browser auto-restarts after 3 failures.

recovering · boolean

true if browser is currently restarting after detecting unhealthy state

Health states

State	Condition	HTTP Status
Healthy	ok: true, browser running	200 OK
Not started	ok: true, browserConnected: false	200 OK
Recovering	recovering: true	503 Service Unavailable
Unhealthy	consecutiveFailures >= 3	200 OK (auto-restart triggered)

Browser lifecycle

• Browser launches lazily on first request (tab creation, navigation, etc.)
• Browser shuts down after 5 minutes of inactivity when no sessions exist (configurable via BROWSER_IDLE_TIMEOUT_MS)
• Browser auto-restarts after 3 consecutive navigation failures

Examples

Healthy (browser running):

curl http://localhost:9377/health

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "consecutiveFailures": 0
}

Healthy (browser idle):

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": false,
  "browserRunning": false,
  "activeTabs": 0,
  "consecutiveFailures": 0
}

Recovering from errors:

curl http://localhost:9377/health
# HTTP 503

{
  "ok": false,
  "engine": "camoufox",
  "recovering": true
}

Start browser

POST /start

Manually launch the browser engine. Useful for pre-warming the browser before the first request.

Response

ok · boolean

true if browser started successfully

browserRunning · boolean

true after successful launch

Example

curl -X POST http://localhost:9377/start

{
  "ok": true,
  "browserRunning": true
}

Notes

• If browser is already running, this endpoint is a no-op and returns success
• First browser launch downloads Camoufox (~300MB) if not already installed
• Subsequent launches take 2-5 seconds

Stop browser

POST /stop

Gracefully shut down the browser engine and close all sessions. Requires authentication.

Authentication

Authorization · string · required

Bearer token matching the CAMOFOX_ADMIN_KEY environment variable:

Authorization: Bearer YOUR_CAMOFOX_ADMIN_KEY

If CAMOFOX_ADMIN_KEY is not set, this endpoint returns 403 Forbidden.

Response

ok · boolean

true if browser was stopped successfully

browserRunning · boolean

false after shutdown

Example

curl -X POST http://localhost:9377/stop \
  -H 'Authorization: Bearer YOUR_CAMOFOX_ADMIN_KEY'

{
  "ok": true,
  "browserRunning": false
}

Shutdown sequence

1. All user sessions are closed (browser contexts)
2. All open tabs are closed
3. Browser process is terminated
4. Browser will relaunch on the next request

Error responses

Missing or invalid admin key:

{
  "error": "Forbidden"
}

Admin key not configured:

{
  "error": "Shutdown endpoint is disabled. Set CAMOFOX_ADMIN_KEY to enable."
}

Auto-recovery

The server automatically monitors browser health and restarts when necessary:

Failure detection

• Tracks consecutive navigation failures
• After 3 consecutive failures, browser is considered unhealthy
• All sessions are closed and browser restarts
• Success resets the failure counter

Disconnection handling

• If browser disconnects unexpectedly, all sessions are cleared
• Browser relaunches on the next request
• Clients receive 500 errors during recovery

Idle shutdown

• When no sessions exist for 5 minutes (default), browser shuts down to free memory
• Server idle memory usage: ~40MB
• Browser relaunches on the next tab creation

Configuration

Variable	Description	Default
BROWSER_IDLE_TIMEOUT_MS	Time before idle shutdown (0 = never)	300000 (5 min)
SESSION_TIMEOUT_MS	Session inactivity timeout	1800000 (30 min)
HANDLER_TIMEOUT_MS	Max time for navigation/interaction	30000 (30s)

Use cases

Health monitoring

# Kubernetes liveness probe
livenessProbe:
  httpGet:
    path: /health
    port: 9377
  initialDelaySeconds: 10
  periodSeconds: 30

Pre-warming

# Launch browser before first user request
curl -X POST http://localhost:9377/start

Graceful shutdown

# Stop browser before server restart
curl -X POST http://localhost:9377/stop \
  -H 'Authorization: Bearer $CAMOFOX_ADMIN_KEY'

Load balancer health checks

# Check if server can accept requests
curl -f http://localhost:9377/health || exit 1

See also

• Environment variables
• Session management
• Docker deployment