Camofox Browser
Deploy Camofox: package, browser binary, native libraries and readiness
Plan a reproducible local browser-service deployment with Node 22, explicit binding and separate service-health and page-readiness tests.
What you will learn
- Track package, browser bundle and native runtime separately.
- A partly pinned Dockerfile is not an immutable build.
- A healthy idle service still needs a real page-readiness test.
Before you start
- Basic HTTP and JSON knowledge
- An isolated service and an owned or permitted test page
Explain the chapter’s actual service boundary and verify the proposed observation or lifecycle fixture.
Key takeaways
- Track package, browser bundle and native runtime separately.
- A partly pinned Dockerfile is not an immutable build.
- A healthy idle service still needs a real page-readiness test.
The JavaScript package is only one artifact
The inspected package requires Node 22 or later and starts with node server.js. It depends on camoufox-js, playwright-core and a native SQLite package. Installing npm dependencies is therefore not sufficient evidence that the browser can launch. Record the package revision, browser bundle, operating system and architecture as separate parts of the deployment manifest.
The README documents a postinstall download and an external CAMOUFOX_EXECUTABLE option for an already managed browser bundle. It warns that the external executable needs its accompanying bundle files, not just a lone binary. Review installation scripts before running them. For a reproducible deployment, pin and verify artifacts rather than relying on whatever a later latest URL happens to serve.
Read the container recipe as a dependency map
The checked Dockerfile uses node:22-trixie-slim and includes GUI, audio, font and software-rendering libraries plus Xvfb. It pins Camoufox version and release arguments, while another download uses the latest yt-dlp release. Consequently, the recipe is not entirely immutable merely because one browser version is pinned. Record or pin all artifacts important to your own rebuild policy.
The Dockerfile also installs build tools for native dependencies and copies mcp and plugin directories needed by runtime imports. Its comments describe failures that can remain hidden behind a healthy HTTP endpoint. Do not optimize build time by removing directories or libraries solely because their names seem unrelated to REST requests; verify imports and the first real tab operation on the target architecture.
Separate listening, health and useful readiness
Set CAMOFOX_BIND_HOST explicitly for the intended network boundary. The inspected server passes an unspecified host to listen when the setting is empty, so do not assume an unconfigured process is loopback-only. For a local test, bind 127.0.0.1 and configure CAMOFOX_ACCESS_KEY. Put any remote deployment behind authenticated access, transport security and controlled browser egress.
GET /health can report success while browserRunning is false after intentional idle shutdown. That is compatible with lazy launch, not proof that a page was rendered. Acceptance needs a separate allowed-page smoke test, snapshot check and resource cleanup. This article supplies a deployment checklist; it does not claim that a container image or complete upstream runtime was built during editorial review.
Implementation steps
- 1
Review the fixed package and installation scripts.
- 2
Record browser bundle and architecture-specific dependencies.
- 3
Bind loopback and configure the global access key for a local test.
- 4
Check /health, then a permitted page and its snapshot before acceptance.
Copy-ready example
{"NODE_ENV":"production","CAMOFOX_BIND_HOST":"127.0.0.1","CAMOFOX_PORT":"9377","CAMOFOX_CRASH_REPORT_ENABLED":"false","secretRequired":"CAMOFOX_ACCESS_KEY supplied separately"}Frequently asked questions
Does HTTP health success mean the browser is ready?
No. Intentional idle shutdown can leave health successful with browserRunning false. Test an allowed page separately.
Can the external executable be copied alone?
The README requires an intact Camoufox bundle with accompanying files. Verify the documented bundle contents for your deployment.
Sources
- README.mdSource checked 2026-09-08
- package.jsonSource checked 2026-09-08
- DockerfileSource checked 2026-09-08
- lib/auth.jsSource checked 2026-09-08
- lib/snapshot.jsSource checked 2026-09-08
- lib/extract.jsSource checked 2026-09-08
- lib/config.jsSource checked 2026-09-08
- lib/reporter.jsSource checked 2026-09-08
- lib/page-lease.jsSource checked 2026-09-08
- server.jsSource checked 2026-09-08
- tests/unit/snapshot.test.jsSource checked 2026-09-08
- tests/unit/auth.test.jsSource checked 2026-09-08