<div align="center"> <img src="engine/additions/browser/branding/ghostfox/logo.png" width="180" alt="Ghostfox" />

Ghostfox

The agent-native stealth browser you can own.

Self-hosted · Open source · MCP-first · Engine-level anti-detect

<img src="docs/demo.gif" width="640" alt="Ghostfox demo: android persona + detection panel" />

· Docs site

</div>

---

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

| | Ghostfox | Hosted stealth (Browserbase etc.) | playwright-mcp | Anti-detect suites (Multilogin etc.) | |---|---|---|---|---| | Self-hosted | ✓ | ✗ | ✓ | partially | | Open source | ✓ | ✗ | ✓ | ✗ | | MCP-native | ✓ | ✓ | ✓ | ✗ | | Engine-level anti-detect | ✓ (C++/Firefox) | vendor partnerships | ✗ | ✓ (closed) | | Coherent identities + auditor | ✓ | ✗ | ✗ | partial | | Runtime language | Rust | — | Node | — |

The moat — why this isn't just another wrapper.

1. 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.
2. 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.
3. 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.
4. 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:

| Family | Native tool | How | |---|---|---| | GeeTest slide / v4 radar | page_geetest_slide | bg-vs-fullbg diff + largest-blob gap detection | | GeeTest icon-click (文字点选) | page_geetest_click | custom-trained YOLOv8s + siamese similarity (rten, CPU) | | Rotate | page_captcha_rotate | 24-angle sweep + programmatic verdict | | Normal OCR | page_captcha_ocr | ported ddddocr (CRNN+LSTM, onnxruntime) | | hCaptcha | page_hcaptcha | layout router + 553-model QIN2DIM zoo + optional vision-model ensemble | | Cloudflare Turnstile / TikTok | captcha_solve + behavioral recipes | proven playbooks in AGENTS.md §6b–6e |

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 — every console.log/warn/error since load
• page_errors — uncaught JS exceptions with stack traces
• page_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

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 (70 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 70 tools — captcha families, pixel/vision tiers, network interception, WebSocket capture/inject/block, identity morph, chrome-mode, Android. Run the server with GHOSTFOX_TOOLSET=full.

The server also publishes instructions (a decision tree agents read before choosing tools) — the disambiguation layer for both tiers.

| Category | Tools | |---|---| | Session | session_create · session_pages · session_me | | See | page_a11y (semantic + login_state + shadow DOM/iframe) · page_extract (typed, token-efficient a11y filters) · page_snapshot · page_screenshot · page_read_ref (full value) · page_diff (observeDiff: what changed since the last snapshot) · page_mutations (M3: unhookable DOM-change whispers) · page_a11y_events (M3: the a11y tree as a stream — focus/text/state/live-region events, the incremental diff) | | Wait | page_wait_for (poll until visible) · page_dismiss_modal · page_wait_stable (render-settled) · page_wait_visual (M3.5: refresh-driver visual stability — the sleep killer) | | Act | page_click_ref · page_click_native (trusted a11y-bounds click: scroll-first, DOM-proof coordinates) · page_click_at (raw trusted coords — no a11y resolution) · page_type_ref · page_click · page_type · page_fill · page_press · page_drag · page_move_to · page_upload_file · page_init_script · page_a11y_set_text (AT-native text input — the Flutter route) | | Captcha | captcha_solve · `page_geetest_s