Installation - Camofox Browser

Prerequisites

Node.js 18+

Required for standalone and plugin installation

~500MB disk space

For Camoufox browser engine (downloads on first run)

Linux/macOS/Windows

Runs on all major operating systems

2GB RAM minimum

Recommended 4GB+ for multiple concurrent sessions

Installation options

npm Package
Standalone
Docker
Cloud Deployment
OpenClaw Plugin

Install from npm

npm install @askjo/camofox-browser

Start the server

npx camofox-browser
# Or if installed globally:
npm install -g @askjo/camofox-browser
camofox-browser

On first run, Camoufox will automatically download the browser engine (~300MB). This is cached locally at ~/.config/camoufox/.

Verify installation

curl http://localhost:9377/health

You should see:

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

Clone from GitHub

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser

Install dependencies

npm install

Start the server

npm start

Or use the shell script:

./run.sh

The server listens on port 9377 by default. Change with CAMOFOX_PORT=8080 npm start.

First-run behavior

When you start the server for the first time:

Camoufox downloads automatically (~300MB, takes 1-2 minutes)
Browser engine is cached at ~/.config/camoufox/
Server starts and listens on port 9377
Browser launches lazily on first tab creation

The postinstall script runs npx camoufox-js fetch to pre-download the browser. If this fails, don’t worry - the download happens on first server start.

Build the image

docker build -t camofox-browser .

Run the container

docker run -p 9377:9377 camofox-browser

The server is now accessible at http://localhost:9377.

With environment variables

docker run -p 9377:9377 \
  -e MAX_SESSIONS=100 \
  -e SESSION_TIMEOUT_MS=3600000 \
  -e BROWSER_IDLE_TIMEOUT_MS=600000 \
  camofox-browser

With proxy support

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

The Docker image includes yt-dlp for fast YouTube transcript extraction. Without Docker, you need to install yt-dlp separately: pip install yt-dlp or brew install yt-dlp.

To use cookie import with Docker:

docker run -p 9377:9377 \
  -e CAMOFOX_API_KEY="your-secret-key" \
  -v ~/.camofox/cookies:/home/node/.camofox/cookies:ro \
  camofox-browser

See Cookie Import for details.

Fly.io

A fly.toml is included in the repository.

fly deploy

Set secrets for sensitive config:

fly secrets set CAMOFOX_API_KEY="your-secret-key"
fly secrets set PROXY_HOST="166.88.179.132"
fly secrets set PROXY_PORT="46040"

Railway

A railway.toml is included.

Connect your GitHub repo to Railway
Railway auto-detects the config and deploys
Set environment variables in the Railway dashboard

Railway provides a public URL automatically. No additional configuration needed.

Generic cloud (AWS, GCP, Azure, DigitalOcean)

Deploy as a standard Node.js application:

Install Node.js 18+ on your VM
Clone the repo and run npm install
Set environment variables (see below)
Start with process manager: pm2 start server.js --name camofox
Configure reverse proxy (nginx/caddy) for HTTPS

Example systemd service (/etc/systemd/system/camofox.service):

[Unit]
Description=Camofox Browser Server
After=network.target

[Service]
Type=simple
User=camofox
WorkingDirectory=/opt/camofox-browser
Environment="NODE_ENV=production"
Environment="CAMOFOX_PORT=9377"
Environment="MAX_SESSIONS=100"
ExecStart=/usr/bin/node server.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable camofox
sudo systemctl start camofox

Install the plugin

openclaw plugins install @askjo/camofox-browser

The plugin auto-starts the server when OpenClaw launches.

Verify plugin is loaded

openclaw plugins list

You should see @askjo/camofox-browser in the list.

Check server status

openclaw camofox status

Output:

Camoufox server: ok
  URL: http://localhost:9377
  Engine: camoufox
  Active tabs: 0
  Managed: true

Available tools

Once installed, your OpenClaw agent has access to:

camofox_create_tab - Create a new browser tab
camofox_snapshot - Get page content with element refs
camofox_click - Click an element
camofox_type - Type text into an element
camofox_navigate - Navigate to URL or search macro
camofox_scroll - Scroll the page
camofox_screenshot - Take a screenshot
camofox_close_tab - Close a tab
camofox_list_tabs - List open tabs
camofox_import_cookies - Import cookies from file

Use Camofox tools instead of the built-in browser tool - they bypass bot detection on Google, Amazon, LinkedIn, etc.

Configure plugin settings

Edit openclaw.json:

{
  "plugins": {
    "entries": {
      "@askjo/camofox-browser": {
        "enabled": true,
        "config": {
          "port": 9377,
          "autoStart": true,
          "maxSessions": 50,
          "sessionTimeoutMs": 1800000
        }
      }
    }
  }
}

Disable built-in browser tool

To use Camofox as the only browser tool:

{
  "tools": {
    "deny": ["browser"]
  }
}

This removes OpenClaw’s built-in browser tool, leaving only Camofox.

Manual server control

Start server

openclaw camofox start

Stop server

openclaw camofox stop

List tabs

openclaw camofox tabs

Environment variables

Configure the server with environment variables:

Core settings

Variable	Description	Default
`CAMOFOX_PORT`	Server port	`9377`
`NODE_ENV`	Environment mode	`development`
`MAX_SESSIONS`	Max concurrent browser sessions	`50`
`MAX_TABS_PER_SESSION`	Max tabs per user session	`10`
`SESSION_TIMEOUT_MS`	Session inactivity timeout	`1800000` (30min)
`BROWSER_IDLE_TIMEOUT_MS`	Kill browser when idle	`300000` (5min)

Performance tuning

Variable	Description	Default
`HANDLER_TIMEOUT_MS`	Max time for any handler	`30000` (30s)
`MAX_CONCURRENT_PER_USER`	Concurrent request cap per user	`3`
`MAX_OLD_SPACE_SIZE`	Node.js V8 heap limit (MB)	`128`
`NAVIGATE_TIMEOUT_MS`	Navigation timeout	`25000` (25s)
`BUILDREFS_TIMEOUT_MS`	Element ref building timeout	`12000` (12s)

Security

Variable	Description	Default
`CAMOFOX_API_KEY`	Enable cookie import endpoint	-
`CAMOFOX_ADMIN_KEY`	Required for `POST /stop`	-
`CAMOFOX_COOKIES_DIR`	Directory for cookie files	`~/.camofox/cookies`

Cookie import is disabled unless CAMOFOX_API_KEY is set. See Cookie Import for setup.

Proxy configuration

Variable	Description	Default
`PROXY_HOST`	Proxy hostname or IP	-
`PROXY_PORT`	Proxy port	-
`PROXY_USERNAME`	Proxy auth username	-
`PROXY_PASSWORD`	Proxy auth password	-

When a proxy is configured:

All traffic routes through the proxy
Camoufox’s GeoIP automatically sets locale, timezone, and geolocation to match the proxy’s exit IP
Browser fingerprint is consistent with proxy location

Example:

export PROXY_HOST=166.88.179.132
export PROXY_PORT=46040
export PROXY_USERNAME=myuser
export PROXY_PASSWORD=mypass
npm start

Resource requirements

Development
Production
Cloud sizing

Minimum:

CPU: 1 core
RAM: 2GB
Disk: 1GB (500MB for Camoufox + dependencies)

Recommended:

CPU: 2 cores
RAM: 4GB
Disk: 2GB

Fly.io

Recommended machine size: shared-cpu-2x (2 vCPU, 4GB RAM)

fly.toml

[vm]
  cpu_kind = "shared"
  cpus = 2
  memory_mb = 4096

Railway

Recommended plan: Starter ($5/month, 512MB RAM, 1 vCPU)For production: Pro ($20/month, 8GB RAM, 8 vCPU)

DigitalOcean

$6/month droplet: 1 vCPU, 1GB RAM - handles 5 concurrent sessions
$12/month droplet: 1 vCPU, 2GB RAM - handles 10 concurrent sessions
$24/month droplet: 2 vCPU, 4GB RAM - handles 20-30 concurrent sessions

Start small and scale up. The browser shuts down when idle, so you pay for actual usage.

Optional dependencies

yt-dlp (YouTube transcripts)

For fast YouTube transcript extraction:

pip install yt-dlp

Without yt-dlp, the /youtube/transcript endpoint falls back to a slower browser-based method.

The Docker image includes yt-dlp by default.

Verify installation

Run these checks to ensure everything works:

Health check

curl http://localhost:9377/health

Should return: {"ok": true, "engine": "camoufox"}

Create a test tab

curl -X POST http://localhost:9377/tabs \
  -H 'Content-Type: application/json' \
  -d '{"userId": "test", "sessionKey": "verify", "url": "https://example.com"}'

Should return a tabId.

Get snapshot

curl "http://localhost:9377/tabs/TAB_ID/snapshot?userId=test"

Should return accessibility tree with “Example Domain” heading.

If step 2 hangs for ~30 seconds, this is normal on first run - Camoufox is launching the browser for the first time.

Troubleshooting

Server won't start

Error: Error: Cannot find module 'camoufox-js'Solution:

npm install

Error: Error: EADDRINUSE: address already in useSolution: Port 9377 is in use. Change port:

CAMOFOX_PORT=8080 npm start

Browser download fails

Error: Error: Browser download failedSolution:

Check internet connection
Retry: npx camoufox-js fetch
If behind a proxy, set HTTP_PROXY environment variable

Manual download:

npx camoufox-js fetch --force

Out of memory errors

Error: JavaScript heap out of memorySolution: Increase Node.js heap size:

node --max-old-space-size=512 server.js

Or set environment variable:

export MAX_OLD_SPACE_SIZE=512
npm start

OpenClaw plugin not loading

Error: Plugin @askjo/camofox-browser failed to loadSolution:

Check plugin is installed: openclaw plugins list
Reinstall: openclaw plugins install @askjo/camofox-browser
Check logs: openclaw logs

Next steps

Quickstart

Try your first browser automation workflow

API reference

Explore all endpoints and parameters

Cookie import

Set up authenticated browsing for LinkedIn, Amazon, etc.

Search macros

Use built-in shortcuts for Google, YouTube, Reddit, and more

Get Started

Core Concepts

Guides

Advanced

​Prerequisites

Node.js 18+

~500MB disk space

Linux/macOS/Windows

2GB RAM minimum

​Installation options

​Install from npm

​Start the server

​Verify installation

​Clone from GitHub

​Install dependencies

​Start the server

​First-run behavior

​Build the image

​Run the container

​With environment variables

​With proxy support

​Mount cookie directory

​Fly.io

​Railway

​Generic cloud (AWS, GCP, Azure, DigitalOcean)

​Install the plugin

​Verify plugin is loaded

​Check server status

​Available tools

​Configure plugin settings

​Disable built-in browser tool

​Manual server control

​Environment variables

​Resource requirements

​Fly.io

​Railway

​DigitalOcean

​Optional dependencies

​yt-dlp (YouTube transcripts)

​Verify installation

​Troubleshooting

​Next steps

Quickstart

API reference

Cookie import

Search macros

Build docs developers (and LLMs) love

Prerequisites

Installation options

Install from npm

Start the server

Verify installation

Clone from GitHub

Install dependencies

Start the server

First-run behavior

Build the image

Run the container

With environment variables

With proxy support

Mount cookie directory

Fly.io

Railway

Generic cloud (AWS, GCP, Azure, DigitalOcean)

Install the plugin

Verify plugin is loaded

Check server status

Available tools

Configure plugin settings

Disable built-in browser tool

Manual server control

Environment variables

Resource requirements

Fly.io

Railway

DigitalOcean

Optional dependencies

yt-dlp (YouTube transcripts)

Verify installation

Troubleshooting

Next steps