All configuration is done through environment variables. Set these before starting the server:
export CAMOFOX_PORT=9377
export MAX_SESSIONS=50
npm start
Server configuration
Core server settings for port and deployment environment.
| Variable | Description | Type | Default |
|---|
CAMOFOX_PORT | HTTP server port | Integer | 9377 |
PORT | Fallback port (used if CAMOFOX_PORT not set) | Integer | 9377 |
NODE_ENV | Node.js environment mode | String | development |
In production mode (NODE_ENV=production), detailed error messages are hidden and only logged server-side.
Example: Custom port
export CAMOFOX_PORT=8080
npm start
# Server runs on http://localhost:8080
Resource limits
Control concurrent sessions, tabs, and memory usage.
| Variable | Description | Type | Default |
|---|
MAX_SESSIONS | Maximum concurrent browser sessions (users) | Integer | 50 |
MAX_TABS_PER_SESSION | Maximum tabs per user session | Integer | 10 |
MAX_TABS_GLOBAL | Global tab limit across all sessions | Integer | 10 |
MAX_CONCURRENT_PER_USER | Concurrent API requests per user | Integer | 3 |
MAX_OLD_SPACE_SIZE | Node.js V8 heap limit in MB | Integer | 128 |
When tab limits are reached, the server will recycle the oldest tab instead of rejecting requests. Monitor MAX_SESSIONS to prevent resource exhaustion.
Example: High-concurrency deployment
export MAX_SESSIONS=100
export MAX_TABS_PER_SESSION=20
export MAX_CONCURRENT_PER_USER=5
export MAX_OLD_SPACE_SIZE=512
npm start
Timeouts
Fine-tune timeout values for different operations.
| Variable | Description | Type | Default |
|---|
SESSION_TIMEOUT_MS | Session inactivity timeout (ms) | Integer | 1800000 (30 min) |
BROWSER_IDLE_TIMEOUT_MS | Kill browser when idle with no sessions (ms, 0=never) | Integer | 300000 (5 min) |
HANDLER_TIMEOUT_MS | Maximum time for any API handler (ms) | Integer | 30000 (30 sec) |
NAVIGATE_TIMEOUT_MS | Page navigation timeout (ms) | Integer | 25000 (25 sec) |
BUILDREFS_TIMEOUT_MS | Element ref building timeout (ms) | Integer | 12000 (12 sec) |
The browser launches lazily on first request and shuts down after BROWSER_IDLE_TIMEOUT_MS with no active sessions. This keeps memory at ~40MB when idle.
Example: Faster timeouts for speed
export HANDLER_TIMEOUT_MS=15000
export NAVIGATE_TIMEOUT_MS=10000
export BUILDREFS_TIMEOUT_MS=6000
npm start
Example: Disable idle shutdown
export BROWSER_IDLE_TIMEOUT_MS=0
npm start
# Browser stays running indefinitely
Proxy configuration
Route all browser traffic through a proxy with automatic GeoIP detection.
| Variable | Description | Type | Default |
|---|
PROXY_HOST | Proxy hostname or IP address | String | - |
PROXY_PORT | Proxy port | Integer | - |
PROXY_USERNAME | Proxy authentication username | String | - |
PROXY_PASSWORD | Proxy authentication password | String | - |
When a proxy is configured, Camoufox’s built-in GeoIP automatically sets browser locale, timezone, and geolocation to match the proxy’s exit IP. This ensures the browser fingerprint is consistent with the proxy location.
Example: Residential proxy
export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start
Docker proxy configuration
docker run -p 9377:9377 \
-e PROXY_HOST=166.88.179.132 \
-e PROXY_PORT=46040 \
-e PROXY_USERNAME=myuser \
-e PROXY_PASSWORD=mypass \
camofox-browser
Security
API keys for protected endpoints (cookie import and server shutdown).
| Variable | Description | Type | Default |
|---|
CAMOFOX_API_KEY | Enable cookie import endpoint (disabled if unset) | String | - |
CAMOFOX_ADMIN_KEY | Required for POST /stop endpoint | String | - |
CAMOFOX_COOKIES_DIR | Directory for cookie files | Path | ~/.camofox/cookies |
Cookie import is disabled by default. If CAMOFOX_API_KEY is not set, the /sessions/:userId/cookies endpoint returns 403. Generate a secure key with openssl rand -hex 32.
Example: Enable cookie import
# Generate a secure key
KEY=$(openssl rand -hex 32)
# Set it in your environment
export CAMOFOX_API_KEY="$KEY"
# Start server
npm start
# Import cookies with Bearer token
curl -X POST http://localhost:9377/sessions/agent1/cookies \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"cookies":[{"name":"session","value":"abc123","domain":"example.com","path":"/"}]}'
Why environment variables?
API keys are secrets and should never be stored in plaintext config files (openclaw.json, config.json, etc.). Instead:
- Set in shell profile (
.bashrc, .zshrc)
- Use systemd unit files (
Environment=CAMOFOX_API_KEY=...)
- Docker/Compose:
env_file: or -e flags
- Fly.io/Railway:
fly secrets set or web dashboard
Example: Custom cookies directory
export CAMOFOX_COOKIES_DIR="/var/camofox/cookies"
mkdir -p /var/camofox/cookies
cp ~/linkedin.txt /var/camofox/cookies/
npm start
OpenClaw plugin configuration
When running as an OpenClaw plugin, the server subprocess inherits these variables from lib/config.js:
// Forwarded to server subprocess
serverEnv: {
PATH: process.env.PATH,
HOME: process.env.HOME,
NODE_ENV: process.env.NODE_ENV,
CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
PROXY_HOST: process.env.PROXY_HOST,
PROXY_PORT: process.env.PROXY_PORT,
PROXY_USERNAME: process.env.PROXY_USERNAME,
PROXY_PASSWORD: process.env.PROXY_PASSWORD,
}
export CAMOFOX_API_KEY=$(openssl rand -hex 32)
openclaw start
Complete example
Production deployment with all variables:
# Server
export CAMOFOX_PORT=9377
export NODE_ENV=production
# Security
export CAMOFOX_API_KEY=$(openssl rand -hex 32)
export CAMOFOX_ADMIN_KEY=$(openssl rand -hex 32)
export CAMOFOX_COOKIES_DIR=/var/camofox/cookies
# Limits
export MAX_SESSIONS=100
export MAX_TABS_PER_SESSION=20
export MAX_CONCURRENT_PER_USER=5
export MAX_OLD_SPACE_SIZE=512
# Timeouts
export SESSION_TIMEOUT_MS=3600000 # 1 hour
export BROWSER_IDLE_TIMEOUT_MS=600000 # 10 minutes
export HANDLER_TIMEOUT_MS=45000
# Proxy (optional)
export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
# Launch
mkdir -p /var/camofox/cookies
npm start
Docker Compose example
version: '3.8'
services:
camofox:
image: camofox-browser
ports:
- "9377:9377"
environment:
- NODE_ENV=production
- MAX_SESSIONS=100
- MAX_TABS_PER_SESSION=20
- SESSION_TIMEOUT_MS=3600000
- BROWSER_IDLE_TIMEOUT_MS=600000
- PROXY_HOST=166.88.179.132
- PROXY_PORT=46040
- PROXY_USERNAME=myuser
- PROXY_PASSWORD=mypass
env_file:
- .env.secrets # CAMOFOX_API_KEY, CAMOFOX_ADMIN_KEY
volumes:
- ./cookies:/home/node/.camofox/cookies:ro
restart: unless-stopped
Validation
The server validates configuration on startup and logs warnings for invalid values. Check logs for:
{"ts":"2026-02-28T10:00:00.000Z","level":"info","msg":"launching camoufox","hostOS":"linux","geoip":true}
{"ts":"2026-02-28T10:00:01.234Z","level":"info","msg":"camoufox launched"}
{"ts":"2026-02-28T10:00:01.235Z","level":"info","msg":"proxy configured","host":"166.88.179.132","port":"46040"}