ghostfox

---

AI エージェントはブロックされます。ヘッドレス Chrome はウェブの約 20% で Cloudflare の 403 を引き起こし、ホスト型の「ステルスブラウザー」では、エージェントの Cookie、ID、セッションが他社のクラウド経由で処理されます。

Ghostfox はその代替です。自分で運用する完全なブラウザースタックとして、フィンガープリントの一貫性を保つステルスエンジンと Rust 製の MCP ランタイムを、1 つのリポジトリにまとめています。

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	ホスト型ステルスブラウザー（Browserbase など）	playwright-mcp	アンチ検出スイート（Multilogin など）
セルフホスト可能	✓	✗	✓	一部
オープンソース	✓	✗	✓	✗
MCP ネイティブ	✓	✓	✓	✗
エンジンレベルのアンチ検出	✓ (C++/Firefox)	ベンダーとの提携	✗	✓（クローズド）
一貫性のある ID + 監査ツール	✓	✗	✗	一部
ランタイム言語	Rust	—	Node	—

優位性の源泉 — これが単なるラッパーではない理由。

1. エンジンを自社で所有しています。 アンチ検出機能は、検出器が読み取れる挿入 JavaScript ではなく、自社の Firefox フォーク内の C++ パッチとして実装されています。上流の Camoufox は一部のパッチをクローズドにする意向を示しています。ラッパーはそのリスクを引き継ぎますが、エンジンを所有するフォークにはそのリスクがありません。
2. 証拠が蓄積され続けるコーパスがあります。 ここでの主張にはすべて実証記録があります。bilibili のアイコンクリック ×6、本番登録での hCaptcha、稼働中の TikTok OAuth+OTP、500/500 の ID 監査、Docker E2E です。機能は1週間でコピーされますが、検証済みの実績はコピーできません。
3. エージェントを前提にした使いやすさです。 一貫性のある43個の MCP ツール、実行後に検証できる記録、証拠の記録、実際の実行からまとめたプレイブック（AGENTS.md）を備えています。エージェント（およびそのプロンプト）はこの環境で習慣を築くため、切り替えコストは現実のものです。
4. 正規の配布経路があります。 PyPI、npm、GHCR、公式 MCP Registry で同一の名前を使い、裏付けとなるドキュメント、ベンチマーク、変更履歴も提供しています。フォークは存在するでしょうが、検証済みの本流はここにあります。

Captcha スイート — 8種類のファミリーをデバイス上で解決（v0.6.7+）。 ランタイムにはローカルモデルを使うネイティブ MCP ソルバーが含まれており、有料の CAPTCHA 解決業者も、クラウドも、ブラウザーのレンタルも不要です。

ファミリー	ネイティブツール	仕組み
GeeTest スライド／v4 レーダー	page_geetest_slide	背景画像と完全背景画像の差分＋最大ブロブのギャップ検出
GeeTest アイコンクリック（文字点选）	page_geetest_click	専用トレーニング済み YOLOv8s＋シャム類似度（rten、CPU）
回転	page_captcha_rotate	24角度のスイープ＋プログラムによる判定
通常の OCR	page_captcha_ocr	移植版 ddddocr（CRNN+LSTM、onnxruntime）
hCaptcha	page_hcaptcha	レイアウトルーター＋553モデルの QIN2DIM zoo＋オプションのビジョンモデルアンサンブル
Cloudflare Turnstile／TikTok	captcha_solve＋行動レシピ	AGENTS.md §6b–6e にある実証済みプレイブック

ベンダーのデモではなく、本番サイトで E2E 検証済みです。bilibili のアイコンクリックで×6回「検証成功」、実際の登録での hCaptcha（dashboard.hcaptcha.com、dosya.co）、稼働中の TikTok OAuth+OTP セッションを確認しています。

デバッグの中枢 — 問題の原因を教えてくれるページツール（v0.7）。 ページが予期しない動作をしたとき、エージェントは推測せずに原因を確認できます。

• page_console — ページ読み込み後のすべての console.log/warn/error
• page_errors — スタックトレース付きの未捕捉 JavaScript 例外
• page_network_start/read/body — リクエスト／レスポンスの取得と本文の読み出し

DevTools の3機能を MCP 経由で利用できます。

マルチモデルビジョン（オプション）。 page_vision＋page_ocr＋ page_match_image＋page_pixels＋page_contrast — ビジョン対応モデル（Cloudflare Workers AI、GLM、Qwen など）を、グリッドパズルやレイアウトに関する質問のクロスチェックとして接続できます。キーは任意です。上記のネイティブソルバーはすべてローカルで動作します。

ネイティブソースからの観察 — page_a11y {"native": true} は、エンジン自身のアクセシビリティツリー（Gecko の DocAccessible の走査、つまり ariaSnapshot の処理基盤）を読み取るため、ページスクリプトによって表示内容が改ざんされることはありません。シャドウ DOM、iframe、ARIA セマンティクスは Gecko 自身が処理し、フォーカス中／必須／チェック済み／展開済み／無効／レベルなど、より豊富な状態も取得できます。ネイティブ参照は観察用ハンドルです。操作にはロール＋名前のアンカー、または JS 走査ソースを使用します。

エージェントの目 — page_a11y。 1回の呼び出しで、安定した参照、セマンティックロール、アクセシブル名、現在の値を持つ、表示中のすべてのインタラクティブ要素を返します。シャドウ DOM と同一オリジンの iframe の内部まで探索するため、ウェブコンポーネントの UI（Reddit、最新のフレームワーク）も完全に確認できます。スナップショットには login_state（ログイン中／ログアウト／不明）、ページ URL、タイトルも含まれます。エージェントは失敗してからではなく、操作前にセッションの状態を確認できます。

エージェントは参照を使って操作します。page_click_ref e38、page_type_ref e21 "text" のように呼び出せるため、CSS セレクターは不要です。リッチエディター（Lexical、Draft、ProseMirror）は、エディター固有の入力経路と実行後に検証できる記録で処理します。page_wait_for を使えば手動で待機する必要はありません。page_read_ref は切り捨てられていない値を返します。page_upload_file はネイティブのファイル選択ダイアログを迂回します。 Android のペルソナにも対応 — session_create {"platform": "android"} を実行すると、ポートレート画面、Adreno／Mali GPU、Android のフォントスタック、Firefox for Android の UA が使用されます。これらはデスクトップの識別情報と同様に監査済みです（500／500 件で整合性を確認済み。詳細は runtime/docs を参照）。

矛盾のない、ひとつの識別情報。 識別情報は整合性のあるデバイスプリセット（プラットフォーム、画面、GPU、実際に同梱されているフォント）から生成され、エンジンレベルで挿入され、使用前に監査されます。偽装ブラウザーにとって最大の敵は、自ら「MacBook で 4 コア」と名乗ることです。

クイックスタート

配布方法を選択してください。

# 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

公式の MCP Registry （io.github.autokeren/ghostfox）にも掲載されています。レジストリ対応クライアントではワンクリックで追加できます。

ソースから：

# 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" }
    }
  }
}

これでエージェントは、session_create → page_open → page_a11y の順に実行し、参照 ID を使って操作できます。

セッションの持ち運びが可能です。 session_create は永続プロファイル用の profile_dir を受け付けます。Cookie、ストレージ、識別情報 TOML がひとつの場所にまとめて保存されるため、再起動後もログイン状態が維持されます。Camoufox 系列の別のブラウザーからセッションを移行する場合は、Cookie をコピーし、識別情報を元のデバイスに合わせてください（プラットフォーム、タイムゾーン、ロケール、画面）。識別情報が突然変わるセッションは、不可能なログインと見なされ、詐欺対策システムによって無効化される可能性があります。実証済みの手順については、AGENTS.md §8 を参照してください。

全ツール一覧（70 ツール） — 2 つのティアを 1 つのバイナリで提供します。

• core（デフォルト）：厳選された 26 のツールです。基本ループ（読み取り → 操作 → 確認）に、デバッグに不可欠なツールを加え、機能が重複するバリエーションはありません。エージェントとレジストリのインスペクターには、すぐに効率的で明確に区別されたツール群が表示されます（各ツールの説明に、どのような場合に優先して使用するかが記載されています）。
• full：70 の全ツールを利用できます。CAPTCHA の各種方式、ピクセル／ビジョンの各ティア、ネットワークのインターセプト、WebSocket のキャプチャ／挿入／ブロック、識別情報の変更、chrome-mode、Android が含まれます。GHOSTFOX_TOOLSET=full を指定してサーバーを実行してください。

サーバーは 指示（ツールを選ぶ前にエージェントが参照する判断ツリー）も公開します。これは両方のティアでツールを明確に使い分けるためのレイヤーです。

カテゴリ	ツール
セッション	session_create · session_pages · session_me
確認	page_a11y（セマンティック情報＋login_state＋shadow DOM/iframe） · page_extract（型指定、トークン効率に優れた a11y フィルター） · page_snapshot · page_screenshot · page_read_ref（値全体） · page_diff（observeDiff：前回のスナップショットからの変更点） · page_mutations（M3：フックできない DOM 変更の通知） · page_a11y_events（M3：ストリームとしての a11y ツリー — フォーカス／テキスト／状態／ライブリージョンのイベント、増分差分）
待機	page_wait_for（表示されるまでポーリング） · page_dismiss_modal · page_wait_stable（レンダリング完了を待機） · page_wait_visual（M3.5：リフレッシュドライバーによる視覚的安定性 — sleep を不要にします）
操作	page_click_ref · page_click_native（信頼された a11y 境界ボックスのクリック：スクロールを先に実行し、DOM に依存しない座標） · page_click_at（生の信頼された座標 — a11y による解決なし） · 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 ネイティブのテキスト入力 — Flutter 用ルート）
Captcha	captcha_solve · page_geetest_slide · page_geetest_click · page_captcha_rotate · page_captcha_ocr · page_hcaptcha · page_captcha_vision（歪んだテキスト CAPTCHA 用のホスト VLM リーダー）
ネットワークブローカー	page_network_intercept（すべてのリクエストを保留） · page_network_resume（url/method/headers/postData を変更） · page_network_abort（ブロック） · page_network_fulfill（レスポンスをモック）
デバッグ	page_console · page_errors · page_network_start · page_network_read（リクエストごとの DNS/TLS/TTFB の時間） · page_network_body · page_frame_stats（M3.5：ジャンク検出器 — フレーム間隔の統計） · page_timing_report（M3.5：ナビゲーションタイミング＋描画） · page_ws_frames（M3：WebSocket ストリーム — 双方向のソケット＋フレーム） · page_ws_send（M3：WS インジェクション — クライアント→サーバーのメッセージ） · page_ws_block（M3：WS ブロック — 双方向のフレームを破棄） · page_ui_audit（M5：レンダリングされた UI の視覚的 QA）
ビジョン	page_vision · page_ocr · page_match_image · page_pixels（コンポジターピクセル — リージョン／セマンティック情報／参照、toDataURL なし） · page_contrast
調査	page_eval · page_open · page_comment
ID	identity_generate · identity_audit · identity_morph（停止→再起動→セッションを失わずに ID を切り替え）
身体感覚	page_proprio（M4：正確な身体状態 — フォーカス、選択範囲／キャレット、スクローラー） · page_cookie_events（M4：Cookie／セッションのハートビート — 認証 Cookie の削除はセッション終了を示す最も早いシグナル） · session_vitals（M4.5：プロセスごとの CPU／メモリ）
レシピ	recipe_record · recipe_save · recipe_list · recipe_replay（決定論的な再生、セマンティックアンカー、厳格／寛容なエスカレーション）
証拠と安全性	session_evidence · confirm_action

すべての変更操作はレシートを返します — page_fill は landed_chars を報告し、type_ref は非同期エディターで実行後に検証するため、ページが気づかれないまま切り替わって編集内容が失われることはありません。人間がエージェントの作業を見たい場合、セッションをヘッドフル（{"headful": true}）で実行することもできます。

すべての実行で証拠が記録されます。 各セッションは、追記専用のイベントログ（events.jsonl）、ページ全体のスナップショット、使用した ID を ~/.ghostfox/recordings/ に保存します — session_evidence でいつでも取得できます。

エミュレーター不要の E2E：Flutter Web ＋ 任意の Web アプリ

Android の E2E では通常、エミュレーター、Appium、デバイスファームが必要です。 Ghostfox は Web の方法を採用しています。Flutter アプリを Web 向けにビルドし （flutter build web — 同じ Dart コードベース）、敵対的なサイトに対して使うものと 同じ機能で操作します。

• セマンティクスツリーをネイティブに読み取る — Flutter のアクセシビリティノード（ロール、 ラベル、境界）が、セマンティクスを有効にすると page_a11y(native=true) に反映されます （アプリ内の 1 行：SemanticsBinding.instance.ensureSemantics()）。
• ネイティブクリック — page_click_native は、信頼できるアクセシビリティ座標で Flutter のボタンを クリックします（検証済み：送信が実行され、ステータスが表示されます）。
• レシート ＋ page_diff ＋ page_mutations ＋ page_wait_stable — 同じ Act→Observe→Compare の証拠ループにより、推測でポーリングする必要はありません。
• ビジュアル QA — page_ui_audit が描画された UI を評価します。

適用範囲について：ロジック／フロー／UI は全面的にカバーされています。実デバイスとの 最終的な視覚的一致（Impeller のレンダリング）とプラットフォームチャネル（センサー、 カメラ）の確認には、引き続きデバイスまたはエミュレーターでのテストが必要です。

スポンサー

Ghostfox は独立して運営され、自己資金で開発されています。チームが CAPTCHA の壁や 雰囲気で書かれたコードによる UI のバグを回避する助けになったら、活動を続けられるよう ご支援ください。

• GitHub Sponsors — 毎月の ご支援。金額は自由です
• Buy Me a Coffee — 1 回限りのご支援

企業向け：スポンサー支援とホスト型 Visual QA サービスの早期アクセスを 受け付けています — リポジトリを支援する か、タイトルを sponsorship にして issue を作成してください。

または、1 つのコマンドでインストール（Linux x86_64）：

curl -fsSL https://raw.githubusercontent.com/autokeren/ghostfox/main/install.sh | bash

ソースからエンドツーエンドでビルドする場合（エンジンを自分でビルド）： engine/README.md を参照してください — make dir && make build。

リポジトリの構成

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)

2 つのディレクトリ、2 つのライセンス、1 つの製品。ランタイムは Juggler をネイティブに使用します — 実行時に Node も Python も必要ありません。

AI エージェント（opencode、Codex、Cursor、Claude Code、 ...）で Ghostfox を使いますか？ まず AGENTS.md をお読みください — 実際のエージェント実行からまとめた 実践ガイドです。READ → REASON → DECIDE → ACT のループ、セルフヘルス （レート制限、下書き、通知）、リッチエディターへの入力方法、既知の壁と それぞれの実証済み解決策を網羅しています。

なぜエンジンを自社で保有するのか？

• 検査に耐えるアンチディテクト。 偽装はエンジン内（navigator、screen、WebGL、fonts、 WebRTC、timezone、audio）で行われます — 検出器が読み取れる注入 JavaScript 内ではありません。
• クラウドへの依存なし。 エージェントの ID と Cookie がサードパーティーのホストに送られることはありません。
• 上流への備え。 engine/ は daijro/camoufox を upstream として追跡します。Ghostfox は独自のブランドを適用しており、上流のパッチが クローズドソースになった場合を含め、必要に応じていつでもリベースできます。

ステータス

v0.7 — アルファ版。検証済み：ID の整合性（500/500）、MCP の完全なラウンドトリップ E2E（作成 → 開く → 入力 → 送信）、本番サイトでの 8 種類の CAPTCHA ファミリーの E2E （bilibili、hCaptcha で保護されたサインアップ、TikTok）、デバッグ用 cortex （コンソール／エラー／ネットワーク）、Docker イメージの E2E（コンテナー内でセッション → 開く → スナップショット）、 Camoufox 系ブラウザー間でのセッションの移植性。 PyPI、npm、Docker（GHCR）、公式 MCP Registry を通じて配布されています。 既知の制限については、runtime/ と engine/ の changelog で追跡しています。

テストする許可を得ていない対象には使用しないでください。 これは テスト／研究用ツールです。

クレジット

Ghostfox は、多くの先人たちの成果を基盤としています — アンチディテクトのパッチスタックを提供する Camoufox（daijro）、エンジンを提供する Mozilla Firefox、パッチツールの系譜を受け継ぐ LibreWolf、そして Juggler プロトコルを提供する Playwright です。

ライセンス

• engine/ — MPL-2.0（Firefox／Camoufox から継承）。engine/LICENSE を参照してください。
• runtime/ — MIT OR Apache-2.0。runtime/LICENSE-MIT を参照してください。