Camofox Browser

What does this agent do, and when should you use it?

Camofox Browser is a self-hosted Node.js browser server built around the Camoufox Firefox engine and exposed through a REST API. Instead of returning raw page HTML, it produces accessibility snapshots with stable element references such as e1 and e2 for subsequent interaction. Each user is assigned an isolated BrowserContext, while sessionKey values organize tab groups and persisted storage can restore cookies and localStorage after restarts. The server launches the browser lazily, shuts it down after idle time, and documents npm, source, Docker, Railway, and Fly.io deployment paths. Optional capabilities include proxy-backed GeoIP settings, Netscape cookie import, VNC login, Playwright traces, YouTube transcript extraction, and anonymized crash and hang telemetry.

A client creates a page with POST /tabs, supplying userId, sessionKey, and url; the service starts Camoufox and opens the page in that user's BrowserContext. GET /tabs/:id/snapshot returns an accessibility snapshot with element refs and can add a base64 PNG through includeScreenshot=true; POST /tabs/:id/click, /type, /press, /scroll, and /navigate perform page actions, with navigate supporting macros such as @google_search and @reddit_search. GET /tabs/:id/links, /images, /downloads, and /screenshot return page links, image metadata, captured downloads, and screenshots; POST /tabs/:tabId/extract accepts a JSON Schema that maps properties to snapshot refs with x-ref. POST /sessions/:userId/cookies injects Playwright cookie objects, GET /sessions/:userId/storage_state exports storage state, and trace:true on the first tab of a session enables Playwright trace archives. POST /youtube/transcript uses yt-dlp when available and otherwise falls back to a browser-based interception method.

1. A developer building a web-research assistant that needs to create pages over HTTP, inspect accessibility snapshots, and act on e1-style references.
2. A team operating browser jobs for multiple users that needs cookies, localStorage, and tabs isolated by userId and restorable after browser restarts.
3. A scraping workflow that must route browser traffic through a residential or backconnect proxy and align browser locale, timezone, and geolocation with the proxy exit IP.
4. An operator who needs to reuse an authenticated website session by importing a Netscape-format cookie file or completing a visual login through the VNC plugin.
5. An engineering team diagnosing flaky browser sessions that needs per-session Playwright traces containing screenshots, DOM snapshots, network activity, and console output.
6. A workflow extracting captions from YouTube URLs that can install yt-dlp for the documented faster transcript path.

What are this agent's strengths and limitations?

How do you install or deploy this agent?

Run from source:

git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install
npm start

The server defaults to http://localhost:9377, and the first run downloads roughly 300MB of Camoufox. Alternatively run:

npx @askjo/camofox-browser

For Docker, use the included build flow:

make up

Cookie import requires a key before startup:

export CAMOFOX_API_KEY="your-generated-key"
npm start

For the faster local YouTube transcript path, install:

pip install yt-dlp

How do you use this agent?

Create a first tab:

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

Use the returned TAB_ID to retrieve a snapshot:

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

Click a reference returned in that snapshot:

curl -X POST http://localhost:9377/tabs/TAB_ID/click \
-H 'Content-Type: application/json' \
-d '{"userId":"agent1","ref":"e1"}'

For deployments beyond loopback, set CAMOFOX_ACCESS_KEY and send Authorization: Bearer <key> with protected requests.

How does this agent compare with similar options?

FAQ