Skip to content
Get packs

Guide · Open source

How to use camofox-browser: install, run and call its API

Updated · written with AI from the project's own documentation and checked against our catalogue data

camofox-browser is an open-source server that runs a modified Firefox browser, built on the Camoufox project, and exposes it through a REST API so AI agents can load and interact with web pages. This guide is for developers who want to run it locally and call it over HTTP. By the end you will have the server running on port 9377 and know the main concepts: accessibility snapshots, element refs and tabs.

camofox-browserjo-inc/camofox-browser · ★ 12.1k · MIT

Quick start

  1. 1Clone the repository. Run git clone https://github.com/jo-inc/camofox-browser and enter the camofox-browser folder.
  2. 2Install dependencies. Run npm install inside the folder. The first run also downloads the Camoufox binary, about 300MB.
  3. 3Start the server. Run npm start. The server listens on http://localhost:9377 by default.
  4. 4Open the API docs. Visit /docs on port 9377 to see the interactive API reference generated from the OpenAPI spec.
  5. 5Create a tab and take a snapshot. Use the API to create a tab, navigate to a page and request an accessibility snapshot.
  6. 6Click an element by ref. Read the element refs such as e1 or e2 in the snapshot and send a click request for the one you need.

What you need before you install

camofox-browser is installed from source with Node.js and npm. The README does not state a minimum Node.js version, so check the project's documentation or use a current LTS release.

The first run downloads the Camoufox browser binary, which the README puts at roughly 300MB. Plan for that disk space and a working network connection.

  • Node.js (version not stated in the README)
  • npm
  • About 300MB of free disk space for the Camoufox download on first run

Install and start the server from source

Clone the repository, move into the folder, install dependencies and start the server. The README says the server listens on http://localhost:9377 by default.

The postinstall step downloads Camoufox on first run. If you already have a Camoufox bundle, you can point the server at it with CAMOUFOX_EXECUTABLE instead of downloading.

  • Default port is 9377
  • Use npx @askjo/camofox-browser to run the published npm package instead of building from source
git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser npm install && npm start

Check that the server responds and read the API docs

Once the server is running, the README points to an auto-generated OpenAPI spec at /openapi.json and interactive docs at /docs on the same port. Open those in a browser to see every endpoint the server offers.

Use these pages as the reference for request formats rather than guessing paths.

  • http://localhost:9377/openapi.json for the OpenAPI spec
  • http://localhost:9377/docs for interactive docs

Understand snapshots and element refs

Instead of returning raw HTML, the server returns simplified accessibility snapshots. The README says these are about 90% smaller than raw HTML, which keeps agent prompts short.

Page elements get stable reference IDs such as e1, e2 and e3. An agent reads the snapshot, picks a ref and asks the server to click or type into that element.

  • Snapshots are simplified accessibility trees, not raw HTML
  • Refs look like e1, e2, e3
  • Large pages are truncated with offset-based pagination

Run it with Docker or on a small machine

The repository includes a Makefile that auto-detects CPU architecture and runs make up. On Windows, the README says to use build.ps1 with Docker Desktop and the WSL2 backend.

The README says the server runs on small hardware such as a Raspberry Pi or a low-cost VPS, because it launches the browser lazily and shuts it down when idle.

  • make up starts the container; make down stops and removes it
  • make reset forces a clean rebuild
  • Do not run docker build directly; use the Makefile or build.ps1
make up make down

Optional: add yt-dlp for YouTube transcripts

The /youtube/transcript endpoint uses yt-dlp when it is installed. Without it, the README says the endpoint falls back to a slower browser-based method. The Docker image already includes yt-dlp.

  • Install with pip install yt-dlp or brew install yt-dlp for local development
pip install yt-dlp

What people use it for

  • Giving an AI agent the ability to read a web page as a simplified accessibility snapshot
  • Scraping sites that block standard headless Chrome or Playwright, as the project describes its goal
  • Running a self-hosted browser API on a Raspberry Pi or low-cost VPS
  • Logging into a site visually through VNC, then exporting storage state for agent reuse
  • Extracting structured data from a page with POST /tabs/:tabId/extract and a JSON Schema

Frequently asked questions

Is camofox-browser free to use?

camofox-browser is released under the MIT licence, according to the README. You can clone it, run it and modify it under those terms. Check the LICENSE file in the repository for the full text.

What do I need to install camofox-browser?

You need Node.js and npm, then you clone the repository and run npm install followed by npm start. The README does not state a minimum Node.js version. The first run downloads a Camoufox binary of about 300MB.

What port does camofox-browser run on?

The default port is 9377, so the server is reachable at http://localhost:9377 after npm start. The README lists this as the default and points to environment variables for other options.

Does camofox-browser guarantee it can access protected sites?

No. The README says the browser changes reduce detection and claims it bypasses some systems such as Cloudflare, but it gives no success guarantees. Test against the sites you need before relying on it.

How is camofox-browser different from Playwright or Puppeteer?

Playwright and Puppeteer are browser automation libraries that you call from code. camofox-browser is a server that runs a modified Firefox and exposes it through a REST API, and the README describes it as a drop-in replacement for those tools. Browserless and SeleniumBase are other comparable projects.

Can I use camofox-browser without writing code?

Not really. The project requires running a Node.js server and calling its HTTP API, so it suits developers rather than people who want a no-code tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

camofox-browser suits developers building AI agents who need a self-hosted browser API that returns compact snapshots and works on sites that block standard headless browsers. It is a poor fit if a plain HTTP fetch is enough, if you need guaranteed access to protected sites, or if you want a no-code tool.

Install options & downloads