Docs

Shuttle 0.1.0.

Install

Get the build from the download page and launch it. It starts without a window and serves MCP on the DevTools port (9222, or a free port recorded in DevToolsActivePort).

Connect a client

Claude Code

claude mcp add --transport http shuttle http://127.0.0.1:9222/mcp

Codex

codex mcp add shuttle --url http://127.0.0.1:9222/mcp

Cursor and any MCP client

Use the Streamable HTTP transport with the URL http://127.0.0.1:9222/mcp, e.g. in Cursor's ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "shuttle": { "url": "http://127.0.0.1:9222/mcp" }
  }
}

Agents and sessions

Agent: a named identity with a color and avatar. Each has its own persistent storage partition (cookies, logins, localStorage), isolated from your browsing and other agents.
Session: a tab group in your normal window. Watch it, hand a tab to an agent, or take it back.
Flow: create-agent once, open-session, allocate-tab, page tools, then release-tab / close-session.

Per-session CDP

Each session has ws://127.0.0.1:9222/devtools/session/<id>. It only sees that session's tabs and that agent's storage. Don't use the browser-wide endpoint for agent work.

Playwright

import { chromium } from 'playwright'

// cdpEndpoint comes from the open-session MCP tool
const cdpEndpoint = 'ws://127.0.0.1:9222/devtools/session/<id>'
const browser = await chromium.connectOverCDP(cdpEndpoint)
const page = browser.contexts()[0].pages()[0]
await page.goto('https://example.com')

agent-browser

agent-browser --cdp ws://127.0.0.1:9222/devtools/session/<id> open https://example.com
agent-browser --cdp ws://127.0.0.1:9222/devtools/session/<id> snapshot

MCP tool reference

Tool	Group	Description
`list-agents`	Agents	List agent identities.
`create-agent`	Agents	Create an agent: id, name, color, avatar. Gets its own storage.
`update-agent`	Agents	Rename or recolor an agent.
`delete-agent`	Agents	Delete an agent and wipe its storage.
`open-session`	Sessions	Open a session (tab group) for an agent. Returns sessionId and cdpEndpoint.
`close-session`	Sessions	Close a session and its tabs.
`list-sessions`	Sessions	List open sessions.
`allocate-tab`	Tabs	Open a tab in a session. Returns targetId and cdpUrl.
`release-tab`	Tabs	Release a tab (hand it back).
`navigate-tab`	Tabs	Navigate a tab to a URL.
`capture-tab`	Tabs	Screenshot a tab, works in the background.
`set-tab-viewport`	Tabs	Set a tab viewport size, e.g. 390x844.
`snapshot`	Page tools	Accessibility snapshot with @eN refs.
`click / dblclick / hover`	Page tools	Pointer actions on a ref.
`fill / type / press`	Page tools	Keyboard and form input.
`select / check / uncheck`	Page tools	Form controls.
`scroll / wait-for`	Page tools	Scroll and wait for conditions.
`screenshot / get-text / find`	Page tools	Read the page.
`eval / console / errors`	Page tools	Run JS, read console and page errors.
`open / back / forward / reload`	Page tools	Navigation.
`state-save / state-load`	Page tools	Save and restore page state.

Network mode: share one Shuttle

Run Shuttle on a dedicated machine and connect from others on your LAN or Tailscale. Off by default.

# On the Shuttle machine
open -a Shuttle --args --shuttle-listen=0.0.0.0     # Linux: ./shuttle --shuttle-listen=0.0.0.0
cat ~/Library/Application\ Support/Shuttle/ShuttleAccessToken   # Linux: ~/.config/shuttle/ShuttleAccessToken

# On any other machine
claude mcp add --transport http shuttle http://shuttle-box:9222/mcp \
  --header "Authorization: Bearer <token>"

--shuttle-listen=<ip> listens on that address (0.0.0.0 for all interfaces, or one IP such as your Tailscale address).
Every client that doesn't connect over loopback needs the access token: Authorization: Bearer <token>, or ?token=<token> for CDP clients that can't set headers. Local clients need no token.
The token is created on first use in the user data dir (ShuttleAccessToken, mode 0600). Set your own with --shuttle-access-token; delete the file to rotate it.
cdpEndpoint and cdpUrl returned by the MCP tools already include the token.
Traffic is plain HTTP: use trusted networks, or Tailscale/WireGuard/SSH, which encrypt it.

Limits

First release: expect rough edges.
No auto-update yet.
Open codecs only: H.264-only video won't play.
No Widevine (no DRM video).
macOS arm64 and Linux x64 only; Windows via WSL2.