Skip to main content
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

StateConditionHTTP Status
Healthyok: true, browser running200 OK
Not startedok: true, browserConnected: false200 OK
Recoveringrecovering: true503 Service Unavailable
UnhealthyconsecutiveFailures >= 3200 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

VariableDescriptionDefault
BROWSER_IDLE_TIMEOUT_MSTime before idle shutdown (0 = never)300000 (5 min)
SESSION_TIMEOUT_MSSession inactivity timeout1800000 (30 min)
HANDLER_TIMEOUT_MSMax time for navigation/interaction30000 (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

Build docs developers (and LLMs) love

Get started for freeTalk to us