Local Mode

Control your real desktop Chrome browser instead of a cloud Playwright instance. Useful for debugging, testing with logged-in sessions, or accessing browser extensions.

Architecture

Local mode uses a native messaging host that Chrome auto-launches when the extension connects. The host serves HTTP on a local port — clients discover it automatically via a port file.

┌─────────────┐       ┌──────────────────┐       ┌───────────────┐
│ browse.sh / │ HTTP  │  Native Host     │ stdio │    Chrome     │
│ MCP Server  │──────>│ (auto-discovered)│<─────>│   Extension   │
│ curl / SDK  │       └──────────────────┘       └───────┬───────┘
└─────────────┘              │                           │
                      Routes commands             Executes actions
                      via X-Tab-Id header         in real browser tabs

Chrome auto-launches the native host binary. It writes its port to ~/.thinkbrowse/port. All clients (browse.sh, MCP server) read this file automatically.

Setup

1. Install the Chrome extension

Install from the Chrome Web Store, or for development: go to chrome://extensions, enable Developer Mode, click "Load unpacked", and select the extension/dist directory.

2. Set up the native host

Open the extension side panel → Settings → follow the native host install instructions. Chrome will auto-launch it when the extension connects — no server to manage.

3. Verify the connection

curl http://localhost:$(cat ~/.thinkbrowse/port)/health
# → { "extensionConnected": true, "connectedTabs": 3, ... }

Using Local Mode

All commands work the same in local and cloud mode — browse.sh auto-detects the mode and routes to the native host or cloud API accordingly.

browse.sh (CLI)

# Same commands work in both local and cloud mode
SID=$(bash scripts/browse.sh session-create)
bash scripts/browse.sh goto "$SID" "https://example.com"
bash scripts/browse.sh snapshot "$SID"
bash scripts/browse.sh click "$SID" "button.submit"
bash scripts/browse.sh session-delete "$SID"

# List tabs (local mode only)
bash scripts/browse.sh tabs

See the CLI (browse.sh) section for the full command reference.

MCP Server (for AI agents)

npx @thinkrun/mcp --mode local

Add to Claude Desktop or any MCP-compatible client. See the MCP package for config examples.

Mode Auto-Detection

All clients (browse.sh, MCP server) auto-detect the mode in this order:

THINKRUN_LOCAL=true env var → local mode
Native host responding (port auto-discovered from ~/.thinkbrowse/port) → local mode
API key available (env var or config file) → cloud mode