Sign inSign up

superbizon007/antidetect-browser-agent

By superbizon007

•Updated 5 months ago

A browser automation agent backed by — a fingerprint-resistant Firefox build.

Image
Machine learning & AI
0

857

superbizon007/antidetect-browser-agent repository overview

⁠antidetect-browser-agent

A browser automation agent backed by — a fingerprint-resistant Firefox build. Exposes Google A2A and OpenAI-compatible APIs over HTTPS. Driven by a vision-language model (VLM) that sees the page as a screenshot and controls it with native browser actions.


⁠Building the container

The build requires passing the shared a2a_agent package as a Docker build context.

# from apps/antidetect_browser_agent/
docker build \
  --build-context a2a_pkg=../../packages/a2a_agent \
  -f Dockerfile.ubuntu \
  -t antidetect-browser-agent:latest \
  .

⁠Running the container

⁠Minimal (pure headless)
docker run -d \
  -p 443:443 \
  -e VLM_URL=https://api.openai.com/v1 \
  -e VLM_API_KEY=sk-... \
  -e VLM_MODEL=gpt-4o \
  antidetect-browser-agent:latest
⁠With VNC monitoring (browser visible)

Set CAMOUFOX_HEADLESS=false so the browser renders on the VNC display.

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

Open http://localhost:6901/?password=vncpassword in a browser to watch the session.

⁠With per-request proxy (Camoufox-level)

Camoufox forwards all browser traffic through the proxy. Each container instance uses the proxy you configure.

docker run -d \
  -p 443:443 \
  -e VLM_URL=... \
  -e VLM_API_KEY=... \
  -e CAMOUFOX_PROXY_SERVER=http://proxy.example.com:8080 \
  -e CAMOUFOX_PROXY_USERNAME=user \
  -e CAMOUFOX_PROXY_PASSWORD=pass \
  -e CAMOUFOX_GEOIP=true \
  antidetect-browser-agent:latest
⁠With system-level transparent proxy (tun2socks)

Routes all TCP/UDP traffic through a SOCKS5 tunnel at the OS level, bypassing the agent-level proxy settings. Useful for routing the entire container through a specific exit node.

docker run -d --cap-add=NET_ADMIN \
  -p 443:443 \
  -e VLM_URL=... \
  -e VLM_API_KEY=... \
  -e SOCKS_PROXY=socks5://user:[email protected]:1080 \
  antidetect-browser-agent:latest
⁠With API key auth
docker run -d \
  -p 443:443 \
  -e VLM_URL=... \
  -e VLM_API_KEY=... \
  -e API_KEY=my-secret-token \
  antidetect-browser-agent:latest

All API requests must then include Authorization: Bearer my-secret-token.


⁠Environment variables

⁠VLM (vision-language model)
VariableDefaultDescription
VLM_URLhttps://api.openai.com/v1OpenAI-compatible API base URL
VLM_API_KEY(required)API key for the VLM
VLM_MODELgpt-4oModel name to use
SEND_IMAGEtrueSet false for text-only LLMs (elements list only, no screenshot)
⁠Camoufox / browser
VariableDefaultDescription
CAMOUFOX_HEADLESStruetrue = pure headless; false = headed (visible in VNC); "virtual" = virtual display (Xvfb)
CAMOUFOX_GEOIPfalseSet locale, timezone, and language based on the proxy IP
CAMOUFOX_HUMANIZEtrueHumanize mouse movements. true = default speed; false = disable; float = custom speed factor
CAMOUFOX_PROXY_SERVER—Proxy URL passed to Camoufox, e.g. http://host:port or socks5://host:port
CAMOUFOX_PROXY_USERNAME—Proxy username
CAMOUFOX_PROXY_PASSWORD—Proxy password
CAMOUFOX_MAIN_WORLD_EVALfalseRun evaluate_js in the page's main world instead of an isolated context
VIEWPORT_WIDTH1920Browser viewport width in pixels
VIEWPORT_HEIGHT1080Browser viewport height in pixels
⁠Agent API
VariableDefaultDescription
API_KEY—Bearer token required on all API requests. Unset = no auth
PORT443HTTPS port the server listens on
AGENT_URLhttps://localhost:{PORT}/Public URL published in the A2A AgentCard
AGENT_NAMEweb.browser.antidetectAgent name in AgentCard
AGENT_VERSION0.1.0Agent version string in AgentCard
AGENT_DESCRIPTION(built-in)Agent description in AgentCard
⁠Shared workspace (S3)

Optional shared workspace for multi-agent pipelines. When WORKSPACE_ID and S3_BUCKET are set the agent mounts the S3 bucket via rclone FUSE and writes its blackboard entry.

VariableDefaultDescription
WORKSPACE_ID—Workspace identifier, e.g. project-abc. Enables workspace mode
WORKSPACE_MOUNT_PATH/workspaceLocal mount point for the S3 FUSE mount
S3_BUCKET—S3 bucket name
S3_ENDPOINT_URL—S3-compatible endpoint URL (omit for AWS S3)
S3_ACCESS_KEY_ID—S3 access key
S3_SECRET_ACCESS_KEY—S3 secret key
S3_REGIONus-east-1AWS region
S3_PREFIX—Optional prefix before WORKSPACE_ID in the bucket
AGENT_IDantidetect_browser_agentUnique name written to the shared blackboard
⁠System-level proxy (tun2socks)
VariableDefaultDescription
SOCKS_PROXY—Route all container traffic through this SOCKS5 proxy, e.g. socks5://user:pass@host:port. Requires --cap-add=NET_ADMIN
PROXY_BYPASS_PRIVATE1Set 0 to also tunnel private RFC-1918 ranges
PROXY_BYPASS_CIDRS—Comma-separated CIDRs to bypass the tunnel
⁠Trajectory recording
VariableDefaultDescription
TRAJECTORY_DIR—Directory to write per-turn trajectory files (screenshot, elements, VLM request/response). Disabled when unset
⁠Element detection (optional integrations)
VariableDefaultDescription
OMNIPARSER_URL—OmniParser API endpoint. When set, replaces JS-based element detection
OMNIPARSER_API_KEY—Bearer token for OmniParser
LOCATOR_URL—UI localization model endpoint for natural-language element queries
LOCATOR_API_KEY—Bearer token for the locator model
LOCATOR_MODELui-tarsLocator model name
⁠VNC
VariableDefaultDescription
VNC_PWvncpasswordVNC and noVNC password
VNC_RESOLUTION1920x1080VNC display resolution
VNC_VIEW_ONLYfalseSet true to disable mouse/keyboard input over VNC

⁠API endpoints

The agent exposes two sets of endpoints over HTTPS on PORT (default 443).

⁠Google A2A (primary)
POST   /                         JSON-RPC 2.0 — tasks/send, tasks/sendSubscribe, etc.
GET    /.well-known/agent.json   AgentCard discovery

Example A2A call:

curl -sk https://localhost:443/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"text": "Go to example.com and return the page title"}]
      }
    }
  }'
⁠OpenAI-compatible
POST   /v1/chat/completions

Example:

curl -sk https://localhost:443/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "antidetect-browser-agent",
    "messages": [
      {"role": "user", "content": "Search for 'camoufox' on Google and return the first result title"}
    ]
  }'
⁠Health check
GET    /health
curl -sk https://localhost:443/health
# {"status":"ok","agent":"web.browser.antidetect"}

⁠VNC access

PortProtocolURL
5901VNCConnect with any VNC client
6901noVNC (HTTP)http://localhost:6901/?password=vncpassword

VNC is only useful when CAMOUFOX_HEADLESS=false. In headless mode the VNC display is blank.


⁠Trajectory recording

When TRAJECTORY_DIR is set, each agent turn writes a folder of debug files:

$TRAJECTORY_DIR/[{context_id}/]{timestamp}/
  turn_NNNN/
    screenshot.png            raw screenshot at step start
    screenshot_marked.png     screenshot with numbered element boxes
    screenshot_annotated.png  screenshot with red circle at click target (click actions only)
    elements.json             detected interactive elements
    llm_0_request.json        VLM request payload
    llm_0_response.json       VLM response and parsed action
    locator.json              locator model request + response (only when LOCATOR_URL is set)
  summary.md                  task plan written at completion

The {context_id} segment is present when the A2A request includes a contextId (multi-turn conversation). {timestamp} is formatted as YYYYMMDD_HHMMSS.

Mount a volume to persist trajectories:

docker run -d \
  -p 443:443 \
  -v /tmp/trajectories:/trajectories \
  -e TRAJECTORY_DIR=/trajectories \
  -e VLM_URL=... \
  -e VLM_API_KEY=... \
  antidetect-browser-agent:latest

⁠docker-compose example

services:
  antidetect-agent:
    image: antidetect-browser-agent:latest
    ports:
      - "443:443"
      - "5901:5901"
      - "6901:6901"
    environment:
      VLM_URL: https://api.openai.com/v1
      VLM_API_KEY: sk-...
      VLM_MODEL: gpt-4o
      API_KEY: my-secret-token
      CAMOUFOX_HEADLESS: "false"
      CAMOUFOX_GEOIP: "true"
      CAMOUFOX_PROXY_SERVER: http://proxy:8080
      CAMOUFOX_PROXY_USERNAME: user
      CAMOUFOX_PROXY_PASSWORD: pass
      TRAJECTORY_DIR: /trajectories
      VNC_PW: changeme
    volumes:
      - ./trajectories:/trajectories
    cap_add:
      - NET_ADMIN   # only needed for SOCKS_PROXY transparent tunnel

⁠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-browser-agent.agents.forfetch.ai/mcp → the worker pod's /mcp.

Tool (skill_id)Description
navigateNavigate to a URL with fingerprint spoofing active
clickClick on an element or coordinates
double_clickDouble-click on an element
typeType text into a focused element
scrollScroll the page
screenshotTake a screenshot of the current page
extract_textExtract text content from the page
evaluate_jsExecute JavaScript in the browser

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

Tag summary

Content type

Image

Digest

sha256:0f9af24c0…

Size

2.1 GB

Last updated

5 months ago

docker pull superbizon007/antidetect-browser-agent