superbizon007/antidetect-ghost-agent repository overview

⁠Ghost Browser Agent

A browser automation agent using Ghost Browser (Chromium-based anti-detect browser) connected via CDP (Chrome DevTools Protocol), controlled by a vision-language model (VLM).

Ghost Browser provides per-tab session isolation with distinct fingerprints, proxies, and cookies — making it well-suited for multi-account automation and anti-bot bypass scenarios.

⁠Architecture

┌─────────────────────────────────────────────┐
│  Docker Container                           │
│                                             │
│  ┌──────────────┐   CDP websocket           │
│  │ Ghost Browser│◄──────────────────────┐  │
│  │ (port 9223)  │                       │  │
│  └──────────────┘                       │  │
│         │ socat                         │  │
│         ▼                               │  │
│  0.0.0.0:9222 (external CDP)           │  │
│                                         │  │
│  ┌──────────────┐                       │  │
│  │ Python API   │  CDPClient ───────────┘  │
│  │ (port 443)   │  LangGraph + VLM         │
│  │ A2A + OpenAI │                          │
│  └──────────────┘                          │
│                                             │
│  VNC :5901 / noVNC :6901                   │
└─────────────────────────────────────────────┘

⁠Build

docker build \
  --build-context a2a_pkg=../../packages/a2a_agent \
  -f Dockerfile.ubuntu \
  -t ghost-browser-agent:latest \
  .

⁠Dev image (browser + VNC only, no API server)

docker build \
  --build-context a2a_pkg=../../packages/a2a_agent \
  -f Dockerfile.dev \
  -t ghost-browser-agent:dev \
  .

⁠Run

docker run -it \
  -p 443:443 \
  -p 6901:6901 \
  -p 5901:5901 \
  -p 9222:9222 \
  -e VLM_URL=https://api.openai.com/v1 \
  -e VLM_API_KEY=sk-... \
  -e VLM_MODEL=gpt-4o \
  ghost-browser-agent:latest

⁠Persist browser sessions across restarts

Mount a host directory to /data/ghost-profile — Ghost Browser will store all sessions, cookies, extensions, and profile data there:

docker run -it \
  -p 443:443 \
  -p 6901:6901 \
  -p 5901:5901 \
  -p 9222:9222 \
  -e VLM_URL=https://api.openai.com/v1 \
  -e VLM_API_KEY=sk-... \
  -e VLM_MODEL=gpt-4o \
  -v /host/path/ghost-profile:/data/ghost-profile \
  ghost-browser-agent:latest

⁠Load custom extensions

The image bundles extensions from files/extensions/ at /data/extensions/ by default. Mount your own directory to override:

  -v /host/path/my-extensions:/data/extensions \

Supported formats:

• .crx files — auto-unpacked at startup (CRX2 and CRX3)
• Unpacked directories — any subdirectory containing manifest.json

Override the path inside the container with GHOST_EXTENSIONS_DIR:

  -e GHOST_EXTENSIONS_DIR=/my/ext/path \
  -v /host/exts:/my/ext/path \

⁠Override the profile path

  -e GHOST_USER_DATA_DIR=/my/custom/path \
  -v /host/path:/my/custom/path \

⁠Environment Variables

⁠Ports

⁠A2A Usage

The agent exposes a Google A2A JSON-RPC interface at https://host:443/.

Agent card: https://host:443/.well-known/agent.json

⁠Notes

• Ghost Browser is an Electron/Chromium app — it requires a display (VNC is always started)
• CDP internal port is 9223; socat forwards 0.0.0.0:9222 → 127.0.0.1:9223
• Ghost Browser binary is expected at /opt/ghost-browser/ghost-browser after dpkg -i; the startup script also checks /opt/ghost-browser-stable/, /usr/bin/, /usr/local/bin/

⁠MCP tools

The agent image exposes an MCP (Model Context Protocol) server on the same port as A2A at /mcp. Any MCP client — Claude Desktop, Cursor, Windsurf, ChatGPT Connectors, OpenAI Agents SDK — can list and invoke these tools using the pod's API_KEY as Bearer.

In production, Core proxies https://antidetect-ghost-agent.agents.forfetch.ai/mcp → the worker pod's /mcp.

Input schemas are authored in apps/agents_mcp/app/seed.py. Skills without an explicit schema advertise a single {task: str} freeform parameter.