<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.**

[![GitHub stars](https://img.shields.io/github/stars/autokeren/ghostfox?style=flat-square&label=stars)](https://github.com/autokeren/ghostfox/stargazers)
[![npm downloads](https://img.shields.io/npm/dm/ghostfox?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/ghostfox)
[![PyPI downloads](https://img.shields.io/pypi/dm/ghostfox?style=flat-square&label=PyPI&color=3776ab)](https://pypi.org/project/ghostfox/)
[![CI](https://img.shields.io/github/actions/workflow/status/autokeren/ghostfox/ci.yml?style=flat-square&label=CI)](https://github.com/autokeren/ghostfox/actions)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.autokeren%2Fghostfox-5b21b6?style=flat-square)](https://github.com/autokeren/ghostfox)
[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ff69b4?style=flat-square)](https://github.com/sponsors/autokeren)

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

[![License](https://img.shields.io/badge/engine-MPL--2.0-orange)](engine/LICENSE)
[![License](https://img.shields.io/badge/runtime-MIT%2FApache--2.0-blue)](runtime/LICENSE-MIT)
[![Engine](https://img.shields.io/badge/engine-Firefox%20152-red)](engine/README.md)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io/servers/io.github.autokeren/ghostfox)
[![PyPI](https://img.shields.io/pypi/v/ghostfox)](https://pypi.org/project/ghostfox/)
[![npm](https://img.shields.io/npm/v/ghostfox)](https://www.npmjs.com/package/ghostfox)
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fautokeren%2Fghostfox-2496ED)](https://github.com/autokeren/ghostfox/pkgs/container/ghostfox)
[![ghostfox MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/autokeren/ghostfox/badges/card.svg)](https://glama.ai/mcp/servers/autokeren/ghostfox)
[![ghostfox MCP server – quality score on Glama](https://glama.ai/mcp/servers/autokeren/ghostfox/badges/score.svg)](https://glama.ai/mcp/servers/autokeren/ghostfox)
[![CI](https://github.com/autokeren/ghostfox/actions/workflows/ci.yml/badge.svg)](https://github.com/autokeren/ghostfox/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/autokeren/ghostfox)](https://github.com/autokeren/ghostfox/releases/latest)
[![Stars](https://img.shields.io/github/stars/autokeren/ghostfox?style=social)](https://github.com/autokeren/ghostfox)

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

[![Watch the full demo](https://img.shields.io/badge/watch-full%20demo%20(video)-a78bfa)](docs/demo.mp4) · [Docs site](https://autokeren.github.io/ghostfox/)

</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](runtime/docs/benchmark-2026-09-08.md)).

**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:

```bash
# 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](https://registry.modelcontextprotocol.io/servers/io.github.autokeren/ghostfox)
(`io.github.autokeren/ghostfox`) — one-click add in registry-aware clients.

From source:

```bash
# 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
```

```json
{
  "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_slide` · `page_geetest_click` · `page_captcha_rotate` · `page_captcha_ocr` · `page_hcaptcha` · `page_captcha_vision` (host-VLM reader for warped text captchas) |
| **Network broker** | `page_network_intercept` (hold every request) · `page_network_resume` (modify url/method/headers/postData) · `page_network_abort` (block) · `page_network_fulfill` (mock the response) |
| **Debug** | `page_console` · `page_errors` · `page_network_start` · `page_network_read` (per-request DNS/TLS/TTFB timing) · `page_network_body` · `page_frame_stats` (M3.5: jank detector — frame-cadence stats) · `page_timing_report` (M3.5: nav-timing + paint) · `page_ws_frames` (M3: the WebSocket stream — sockets + frames both directions) · `page_ws_send` (M3: WS injection — client→server message) · `page_ws_block` (M3: WS blocking — drop frames both directions) · `page_ui_audit` (M5: visual QA of the rendered UI) |
| **Vision** | `page_vision` · `page_ocr` · `page_match_image` · `page_pixels` (compositor pixels — region/semantic/ref, no toDataURL) · `page_contrast` |
| **Inspect** | `page_eval` · `page_open` · `page_comment` |
| **Identity** | `identity_generate` · `identity_audit` · `identity_morph` (stop→relaunch→swap identity without losing the session) |
| **Body sense** | `page_proprio` (M4: honest body state — focus, selection/caret, scrollers) · `page_cookie_events` (M4: cookie/session heartbeat — auth-cookie deletion = earliest session-death signal) · `session_vitals` (M4.5: per-process CPU/memory) |
| **Recipes** | `recipe_record` · `recipe_save` · `recipe_list` · `recipe_replay` (deterministic replay, semantic anchors, strict/lenient escalation) |
| **Evidence & safety** | `session_evidence` · `confirm_action` |

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`.

## 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_native` fires 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_audit` judges 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](https://github.com/sponsors/autokeren) — monthly
  support, any amount
- [Buy Me a Coffee](https://www.buymeacoffee.com/autokeren) — one-time

Companies: sponsorship + early access to the hosted Visual QA service
is open — [sponsor the repo](https://github.com/sponsors/autokeren)
or open an issue with the title `sponsorship`.

**Or install in one command** (Linux x86_64):

```bash
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](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](https://github.com/microsoft/playwright) natively — no Node, no
Python at runtime.

> **Using Ghostfox with an AI agent (opencode, Codex, Cursor, Claude Code,
> ...)?** Read [`AGENTS.md`](AGENTS.md) first — 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](https://github.com/daijro/camoufox)
  as `upstream`; 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](https://github.com/daijro/camoufox) (daijro) for the anti-detect
patch stack, [Mozilla Firefox](https://www.mozilla.org/firefox/) for the
engine, [LibreWolf](https://librewolf.net/) for the patch tooling lineage, and
[Playwright](https://github.com/microsoft/playwright) for the Juggler protocol.

## License

- `engine/` — **MPL-2.0** (inherited from Firefox / Camoufox). See [engine/LICENSE](engine/LICENSE).
- `runtime/` — **MIT OR Apache-2.0**. See [runtime/LICENSE-MIT](runtime/LICENSE-MIT).