deaddev/browser repository overview

⁠browser

Headless Browser (Chrome/Chromium) with a builtin web tool to interactive with the browser.

docker pull deaddev/browser
# or
docker pull ghcr.io/zigzagt/browser

linux/amd64, linux/arm64 — Playwright installs Chrome for Testing⁠ on amd64, Chromium on arm64.

⁠Supported Tags

⁠Components

The image has a layered wrapper chain and a CDP proxy server:

⁠Usage

⁠Run as standalone browser

docker run -d --init --name browser --shm-size=1g \
  -p 6080:6080 \
  deaddev/browser

Open http://<host>:6080 to access the browser.

⁠docker compose

services:
  browser:
    init: true
    image: deaddev/browser
    shm_size: 1g
    ports:
      - "6080:6080"
    environment:
      CHROME_USER_DATA_DIR: /data  # persist profile (cookies, sessions, extensions); omit for ephemeral
    volumes:
      - browser-data:/data
    devices:
      - /dev/dri:/dev/dri  # GPU acceleration on Linux hosts (Intel/AMD)

volumes:
  browser-data:

Drop the devices line if your host has no /dev/dri (macOS, Windows). The container falls back to bundled SwiftShader (CPU rendering) automatically.

⁠GPU acceleration

The image ships with software rendering (SwiftShader) by default. To enable hardware acceleration on Linux hosts:

⁠Use as base image

Set executablePath to chrome in puppeteer/playwright.

FROM deaddev/browser

RUN npm install -g your-app

CMD ["your-app"]

const browser = await puppeteer.launch({ executablePath: 'chrome' });

When called with --* flags (as puppeteer/playwright do), chrome starts the bridge in the background then execs into the browser directly.

⁠Start and stop

⁠Custom Chrome flags

Append extra flags to any start command. Such as chrome [... your args].

docker run -d --init --shm-size=1g -p 6080:6080 \
  deaddev/browser chrome --proxy-server=socks5://host:1080

⁠Drive from agents (MCP)

The bridge exposes a Model Context Protocol (MCP) endpoint at /mcp so any MCP-capable agent can drive this browser as a tool. Streamable-HTTP transport, stateless.

Add to your agent's MCP config (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "browser": {
      "type": "http",
      "url": "https://<your-bridge-host>/mcp"
    }
  }
}

The MCP server also sends an instructions field at the initialize handshake with a full workflow guide; agents typically read it automatically. The table below is a summary.

Discovery and tab management:

Reading pages (pick the right tool):

Interacting (trusted CDP input — passes bot detection):

Human-in-the-loop:

⁠Recommended workflow

1. browser_list_tabs — see what's there.
2. Reuse: browser_navigate(tabId, url) if an existing tab fits. Otherwise browser_open(url).
3. browser_get_snapshot(tabId) — agent-readable view with [uid=N] markers.
4. browser_click({tabId, uid}) / browser_type({tabId, uid, text}) / browser_press_key({tabId, key}) — drive the page.
5. Pass includeSnapshot: true on an action to receive a fresh snapshot in the same response.

Agents don't manage cleanup — FIFO auto-closes the oldest MCP-owned tab when you exceed MCP_MAX_OPEN_TABS (default 3).

⁠MCP-owned tabs vs user-opened tabs

• MCP-owned: opened via browser_open. Counted against the FIFO cap.
• User-owned: opened by the human in the viewer, or by another channel. Never counted against FIFO, never auto-closed.
• browser_navigate(tabId, url) works on either without affecting ownership.
• An attention-bearing tab — MCP-owned or user-owned — is protected from FIFO eviction. browser_open errors with a clear message naming the protected tab if it would be evicted.
• Survives restarts. MCP-ownership and attention are persisted to the profile dir and re-established after a bridge or browser restart. Each owned tab carries a sessionStorage marker (history-hash fallback for opaque origins) that's matched back to the restored tab even though Chrome assigns new internal ids. Requires a persistent profile (CHROME_USER_DATA_DIR set) and, for a browser restart, that Chrome is configured to restore the session ("continue where you left off"); with an ephemeral profile there's nothing to restore and recovery is a no-op.

⁠Captcha / human-in-the-loop workflow

When a page presents a captcha, MFA, paywall, or any human-only verification:

1. browser_set_attention(tabId, "Please solve the captcha so I can continue.") — multi-paragraph messages are supported.
2. browser_wait_for(tabId, "<expr that goes truthy post-resolution>", timeoutMs) — e.g. wait for a post-captcha element.
3. browser_dismiss_attention(tabId).

The viewer pulses the tab's blinking dot and renders the message in a floating box on that tab. Concurrent attention requests are capped at MCP_MAX_ATTENTION (default 3).

Notes:

• All tabs are shared across agents — browser_list_tabs first, reuse where possible.
• Tools intentionally avoid enabling Runtime/Console/Debugger CDP domains, so the browser stays clean for bot-detection sites.

⁠Reverse proxy

Reverse proxy is supported out of the box, with or without a URL prefix. No configuration needed on the bridge side.

For example:

location /my-browser/ {
    proxy_pass http://browser:6080/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Access at https://my-nginx.com/my-browser

⁠Configuration