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 Chrome DevTools Protocol input):

Text replacement, pointer movement, and selection follow browser input behavior rather than assigning values or dispatching synthetic DOM (Document Object Model) events. Tool and viewer input are serialized per tab so compound gestures do not interleave. Drags use an explicit origin rather than relying on pointer position left by earlier input. Native option clicks use keyboard selection when pointer geometry is unavailable. Trusted events alone do not guarantee acceptance by bot detection.

Element clicks, typing, selection, scrolling locations, and pointer movement first use an exposed point without scrolling. They automatically use native wheel input when the target is offscreen or clipped, including nested scroll containers. Partially covered elements can be clicked on an exposed part; sticky overlays can be avoided by repositioning the target. Briefly covered targets are retried. Coordinate targets stay literal, and drag endpoints must be visible together.

The tools do not remove overlays, force-click hidden elements, or silently switch to JavaScript scrolling. A persistent modal, hidden control, or page that prevents scrolling still produces an explicit error rather than clicking the wrong element. Native option selection is the semantic fallback: a normal left click without modifiers, double-click, or hold delay selects that exact option using keyboard input and returns method: "keyboard" and selectedValues, rather than a fictitious clickedAt. When browser_scroll first reveals an offscreen location, its revealed field reports that preparation separately from the requested scroll.

Native input temporarily activates the target tab so Chromium can deliver events to background pages, then restores the tab currently shown in the viewer. Explicit JavaScript scrolling does not activate the tab.

Dragging uses one call:

browser_move_pointer({
  tabId, from: { uid: sourceUid }, to: { uid: destinationUid }, mouseButton: "left"
})

Both from and mouseButton are required for dragging; omit both for ordinary movement. Each point accepts {uid}, {selector}, or {x, y}. Another agent or the viewer can move the pointer between calls, so a previous move is not a drag origin. Coordinates are CSS (Cascading Style Sheets) pixels relative to the visible page's top-left corner, not document or screen coordinates.

⁠Native select rendering and remaining limits

Changing a native selection and displaying its popup are separate capabilities. The bridge now opts both ordinary dropdown controls and their ::picker(select) into appearance: base-select. This completes the existing styling workaround so menus are visible and mouse-operable in bridge frames. Multiple and sized listboxes remain native to preserve their keyboard behavior. Existing bridge styles are updated in place when a tab is attached, so a bridge-only restart also upgrades pages carrying the previous incomplete rule.

Measured on Linux headless Chrome/153.0.8010.12, 2026-10-21, through the actual bridge and its viewer frame protocol (tests/77-native-select.mjs):

The measurement compares pixels outside the closed control in fresh bridge frames, not just the document's option values. Native and previous-bridge modes produced zero changed pixels there, while screenshots contained the popup. Their options had zero document geometry. Fully opted-in options had geometry and the menu appeared in both capture paths.

Keyboard input and value-based selection worked with initially open and closed pickers in all three modes. Native popup mouse selection failed both through the viewer and direct Chrome DevTools Protocol input, using option coordinates measured from screenshots. Page.bringToFront left the popup open, so the failure is not explained solely by the bridge's activation wrapper. The exact native-popup mouse-routing cause remains unverified. Public Input.synthesizeTapGesture calls with mouse and touch sources also failed to change the native selection in this fixture; they are not a fallback.

The previous injected rule was incomplete. Chrome's customizable-select documentation⁠ requires opting in both the control and its picker. It also documents changes to sizing, placement, and operating-system integration. Applying that mode changes website rendering; this is a compatibility workaround, not native popup capture. Higher-priority author styles and controls outside the injected document styles, including shadow roots, can retain native popups. Their option actions fall back to trusted keyboard selection, but that does not repair native popup mouse routing or put those menus into screencast frames.

Screenshots and screencasts use different capture paths: the protocol⁠ does not expose an equivalent popup-inclusion switch on startScreencast. Chromium's RenderWidgetHostViewAura::CopyFromSurfaceImpl calls CopyMainAndPopupFromSurface⁠, whereas PageHandler::StartScreencast uses a video consumer. These source paths explain why screenshot visibility must not be treated as screencast coverage.

Native popup capture and mouse routing remain separate limitations. The current policy completes the existing stylesheet without replacing website controls or changing the capture architecture. Passing selection tests alone does not establish native-popup rendering support; test 77 measures the actual bridge frames and input paths separately.

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