Ghostfox
The agent-native stealth browser you can own.
Self-hosted · Open source · MCP-first · Engine-level anti-detect
AI agents get blocked. Headless Chrome triggers Cloudflare 403s on ~20% of the web, and hosted "stealth browsers" route your agent's cookies, identities and sessions through someone else's cloud.
Ghostfox is the alternative: a complete browser stack you run yourself — a fingerprint-coherent stealth engine plus a Rust MCP runtime, in one repo.
Firefox (MPL-2.0)
└─ Camoufox (anti-detect patches, by daijro)
└─ Ghostfox engine engine/ — spoofing at the C++ level
└─ Ghostfox runtime runtime/ — Rust: sessions, identities, MCP
The moat — why this isn't just another wrapper.
- We own the engine. The anti-detect lives in C++ patches inside our own Firefox fork — not in injected JS that detectors can read. Upstream Camoufox has signaled partially-closed patches ahead; wrappers inherit that risk, a fork that owns its engine doesn't.
- A living proof corpus. Every claim here has a receipt: bilibili icon-click ×6, hCaptcha on production signups, TikTok OAuth+OTP live, 500/500 identity audits, Docker E2E. Features get copied in a week — verified history can't be.
- Agent-native ergonomics. 43 coherent MCP tools, fire-then-verify
receipts, evidence recording, and a playbook (
AGENTS.md) distilled from real runs. Agents (and their prompts) build habits on this surface — switching costs are real. - Canonical distribution. PyPI, npm, GHCR and the official MCP Registry under one name, with the docs, benchmarks and changelogs to back it. Forks will exist; the verified trunk is here.
Captcha suite — 8 families, solved on-device (v0.6.7+). The runtime ships native MCP solvers with local models — no paid captcha farms, no cloud, no browser rent:
E2E-verified against production sites (not vendor demos): bilibili icon-click ×6 "Verification Succeeded", hCaptcha on real signups (dashboard.hcaptcha.com, dosya.co), TikTok OAuth+OTP live session.
Debug cortex — page tools that tell you WHY (v0.7). Agents stop guessing when a page misbehaves:
page_console— everyconsole.log/warn/errorsince loadpage_errors— uncaught JS exceptions with stack tracespage_network_start/read/body— request/response capture with body fetch
That's the DevTools trio, exposed over MCP.
Multi-model vision (optional). page_vision + page_ocr +
page_match_image + page_pixels + page_contrast — wire any
vision-capable model (Cloudflare Workers AI, GLM, Qwen, ...) as
cross-checks for grid puzzles and layout questions. Keys are optional;
the native solvers above run fully local.
Native-sourced observation — page_a11y {"native": true} reads the
engine's OWN accessibility tree (Gecko's DocAccessible walk — the
ariaSnapshot plumbing), so page scripts cannot tamper with what you see:
shadow DOM, iframes and ARIA semantics handled by Gecko itself, richer
states (focused/required/checked/expanded/disabled/level). Native refs
are observation handles; acting goes through role+name anchors or the
JS-walk source.
Eyes for agents — page_a11y. One call returns every visible interactive
element with a stable ref, semantic role, accessible name, live value —
piercing shadow DOM and same-origin iframes, so web-component UIs
(Reddit, modern frameworks) are fully visible. The snapshot also reports
login_state (logged-in / logged-out / unknown), page URL and title —
agents check session health before acting, not after failing.
Agents act by ref: page_click_ref e38, page_type_ref e21 "text" — no CSS
selectors needed. Rich editors (Lexical, Draft, ProseMirror) are handled via
editor-native input paths with fire-then-verify receipts. page_wait_for
replaces manual sleeps. page_read_ref gives full untruncated values.
page_upload_file bypasses native file pickers.
Android personas too — session_create {"platform": "android"} gives
portrait screens, Adreno/Mali GPUs, Android font stacks and Firefox-on-Android
UAs, all audited like desktop identities (500/500 coherent, see
runtime/docs).
One identity, no contradictions. Identities are generated from coherent device presets (platform, screen, GPU, fonts that actually ship together), injected at the engine level, and audited before use — a spoofed browser's worst enemy is itself saying "4 cores on a MacBook".
Quickstart
Pick a distribution:
# Python (Linux x86_64)
pip install ghostfox
python -c "import ghostfox; ghostfox.install_engine(); ghostfox.install_runtime()"
# npm / any MCP host
npm install -g ghostfox # or: npx ghostfox install
{
"mcpServers": {
"ghostfox": { "command": "npx", "args": ["-y", "ghostfox", "mcp"] }
}
}
# Docker (engine + MCP runtime, ubuntu:24.04 base)
docker run -i --rm ghcr.io/autokeren/ghostfox:v0.7.2
# or one-line install of the binary stack:
curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash
# Windows (PowerShell):
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/autokeren/ghostfox/main/install.ps1 | iex"
Also listed on the official
MCP Registry
(io.github.autokeren/ghostfox) — one-click add in registry-aware clients.
From source:
# 1) Get the engine (prebuilt) and unpack it somewhere, e.g. /opt
unzip ghostfox-<ver>-lin.x86_64.zip -d /opt/ghostfox
# 2) Build the runtime
git clone https://github.com/autokeren/ghostfox.git
cd ghostfox/runtime
cargo build --release
{
"mcpServers": {
"ghostfox": {
"command": "/path/to/ghostfox/runtime/target/release/ghostfox-mcp",
"env": { "GHOSTFOX_HOME": "/opt/ghostfox" }
}
}
}
Then the agent can: session_create → page_open → page_a11y → act by ref.
Portable sessions. session_create accepts profile_dir for persistent
profiles: cookies, storage and the identity TOML live together in one place,
so a login survives restarts. Migrating a session from another
Camoufox-lineage browser? Copy the cookies and match the identity to the
origin device (platform, timezone, locale, screen) — a session that
suddenly changes identity looks like an impossible login and anti-fraud
systems revoke it. Proven flow, see AGENTS.md §8.
Full tool surface (71 tools) — two tiers, one binary:
core(default): 26 curated tools — the golden loop (read → act → verify) plus debugging essentials, zero overlapping variants. This is what agents and registry inspectors see out of the box: an efficient, disambiguated surface (each tool's description says when to prefer it).full: all 71 tools — captcha families, pixel/vision tiers, network interception, WebSocket capture/inject/block, identity morph, chrome-mode, Android, page_download (browser-identity media harvesting). Run the server withGHOSTFOX_TOOLSET=full.
The server also publishes instructions (a decision tree agents read before choosing tools) — the disambiguation layer for both tiers.
Every mutation returns a receipt — page_fill reports landed_chars, while
type_ref fire-then-verifies async editors, so a silent page swap can't eat an
edit unnoticed. Sessions can also run headful ({"headful": true}) when
humans want to watch the agent work.
Every run records evidence. Each session writes an append-only event log
(events.jsonl), full page snapshots and the identity it used under
~/.ghostfox/recordings/ — fetch it any time with session_evidence.
Engine diagnostics. ghostfox-mcp --self-test walks the engine
pipeline (detection → spawn → juggler handshake → Browser.enable) and
prints a step-by-step report plus the engine's stderr tail on failure —
paste the output into an issue when a platform misbehaves.
E2E without emulators: Flutter web + any web app
Android E2E normally means emulators, Appium and a farm of devices.
Ghostfox takes the web route: build the Flutter app for the web
(flutter build web — same Dart codebase) and drive it with the
same senses used against hostile sites:
- Semantics tree, read natively — Flutter's a11y nodes (roles,
labels, bounds) land in
page_a11y(native=true)once semantics are enabled (one line in the app:SemanticsBinding.instance.ensureSemantics()). - Native clicks —
page_click_nativefires the Flutter buttons at their trusted a11y coordinates (verified: submit triggers, status renders). - Receipts +
page_diff+page_mutations+page_wait_stable— the same Act→Observe→Compare evidence loop, no polling guesswork. - Visual QA —
page_ui_auditjudges the rendered UI.
Honest scope: logic/flow/UI = fully covered; final visual parity with real devices (Impeller rendering) and platform channels (sensors, camera) still need a device or emulator pass.
Sponsor
Ghostfox is independent and self-funded. If it saves your team from captcha walls or vibe-code UI bugs, help keep the house open:
- GitHub Sponsors — monthly support, any amount
- Buy Me a Coffee — one-time
Companies: sponsorship + early access to the hosted Visual QA service
is open — sponsor the repo
or open an issue with the title sponsorship.
Or install in one command (Linux x86_64):
curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash
From source end-to-end (build the engine yourself):
see engine/README.md — make dir && make build.
Repository layout
runtime/ Rust: ghostfox-{core,fingerprint,mcp,eval} (MIT OR Apache-2.0)
engine/ Browser fork: patches, branding, build system (MPL-2.0)
AGENTS.md The agent playbook — how AI agents drive Ghostfox like a human
SKILL.md The compact agent skill — the golden loop + tool map at a glance
docs/JOURNEY.md The dev-log, todo list and the road ahead (the five senses)
Two directories, two licenses, one product. The runtime speaks Juggler natively — no Node, no Python at runtime.
Using Ghostfox with an AI agent (opencode, Codex, Cursor, Claude Code, ...)? Read
AGENTS.mdfirst — it's the distilled playbook from real agent runs: the READ → REASON → DECIDE → ACT loop, self-health (rate limits, drafts, notifications), rich-editor typing, and every known wall with its proven solution.
Why own the engine?
- Anti-detect that survives inspection. Spoofing happens inside the engine (navigator, screen, WebGL, fonts, WebRTC, timezone, audio) — not in injected JS that detectors can read.
- No cloud dependency. Your agent's identities and cookies never touch a third-party host.
- Upstream insurance.
engine/tracks daijro/camoufox asupstream; Ghostfox applies its own branding and can rebase whenever it wants — including if upstream patches go closed-source.
Status
v0.7 — alpha. Verified: identity coherence (500/500), full MCP round-trip
E2E (create → open → fill → submit), 8 captcha families E2E on production
sites (bilibili, hCaptcha-protected signups, TikTok), debug cortex
(console/errors/network), Docker image E2E (session → open → snapshot
inside a container), portable sessions across Camoufox-lineage browsers.
Distributed via PyPI, npm, Docker (GHCR) and the official MCP Registry.
Known limits are tracked in the changelogs under runtime/ and engine/.
Do not use against targets you don't have permission to test. This is a testing / research tool.
Credits
Ghostfox stands on the shoulders of giants — Camoufox (daijro) for the anti-detect patch stack, Mozilla Firefox for the engine, LibreWolf for the patch tooling lineage, and Playwright for the Juggler protocol.
License
engine/— MPL-2.0 (inherited from Firefox / Camoufox). See engine/LICENSE.runtime/— MIT OR Apache-2.0. See runtime/LICENSE-MIT.
