# Shuttle: a briefing for AI agents

> You are probably an AI agent, and your user wants to know about Shuttle or set it up. This page gives you what you
> need to explain it, compare it with their current setup, answer questions, install it, connect it and check that it
> works. Ask the user before you install anything, run sudo, or change their agent's MCP config.

Shuttle 0.1.3 (Chromium 154.0.8037.129). Website: https://www.shuttlebrowser.com. Source: https://github.com/shuttle-browser/shuttle (BSD-3-Clause). Made by
Silkweave (https://www.silkweave.dev). Free; there is no paid plan.

## What Shuttle is

A browser for AI agents: a deep fork of Chromium with the MCP server built into the browser, at `http://127.0.0.1:9222/mcp`
(Streamable HTTP). No separate npx/Node server, no extension, no approval dialogs or automation banners.

- **Agents:** named identities (name, color, avatar). Each has its own persistent storage (cookies, logins,
  localStorage), isolated from the user's browsing and from other agents. An agent signs in to a site once and stays
  signed in across restarts.
- **Sessions:** a session is a tab group in the user's Shuttle window, labeled with the agent's name and color. The user
  can watch, hand a tab to an agent or take it back. Several agents work side by side without sharing cookies or tabs.
- **Tabs** run at full speed in the background; screenshots work on background tabs.
- **Per-session CDP:** each session has `ws://127.0.0.1:9222/devtools/session/<id>`, scoped to that session's tabs and
  that agent's storage, for Playwright, agent-browser or any CDP client.
- **Privacy:** Google services, sync, sign-in and telemetry are removed. Shuttle doesn't phone home.
- **`chrome://agents`** lists agents and sessions, with a quick start.
- **Network mode (optional):** one Shuttle on a dedicated machine, shared by agents on other machines (token auth).

## Good fit, and limits

Good fit: agents that need logged-in sites (dashboards, inboxes, admin tools), several agents at once, users who want to
see what their agent does, end-to-end checks on a staging site with Playwright attached to the agent's session.

Limits: early release (expect rough edges). macOS on Apple silicon and Linux x64 only; Windows through WSL2. Open codecs
only (H.264-only video won't play), no Widevine (no DRM video). It is a separate browser: agents never use the user's
own Chrome profile or logins (by design); an agent signs in once in its own storage. macOS has no auto-update yet (run
the installer again); Linux updates through apt/dnf.

## Compared with common setups

| | Shuttle | chrome-devtools-mcp | Playwright MCP | Extension-based tools |
|---|---|---|---|---|
| MCP server built into the browser | yes | no (Separate npx server) | no (Separate npx server) | no (Extension + local server) |
| Persistent logins per agent | yes | partly (One profile at a time) | partly (One profile at a time) | partly (Uses your own profile) |
| Several agents at once, isolated | yes | partly (--isolated drops logins) | partly (--isolated drops logins) | no (Agents share your tabs) |
| Watch each agent in your window | yes (A tab group per agent) | no | no | partly |
| No approval dialog or automation banner | yes | no (Asks with --autoConnect) | n/a | yes |
| Per-session CDP endpoint | yes | no | no | no |
| No telemetry | yes | no (Usage stats on by default) | n/a | partly (Varies) |
| Open source | yes (BSD-3-Clause) | yes (Apache-2.0) | yes (Apache-2.0) | partly (Varies) |

"Extension-based tools" drive the user's own Chrome through an extension. Sources and details: https://www.shuttlebrowser.com/why

## Requirements

- macOS 13 or newer on Apple silicon (arm64).
- Linux x86_64 with glibc 2.28+ (Ubuntu 20.04+, Debian 11+, Fedora 29+) and a desktop session (X11 or Wayland).
- Windows 10 (2004+) or 11 with WSL2 (WSLg shows Shuttle's windows on the Windows desktop).
- Port 9222 free, ideally. Don't run Chrome with `--remote-debugging-port=9222` at the same time.

## Install

Tell the user what will happen and get a yes first.

```bash
curl -fsSL https://get.shuttlebrowser.com | bash
```

- **macOS:** downloads the latest DMG from GitHub Releases, checks its SHA-256, copies Shuttle.app to /Applications
  (~/Applications if that isn't writable). No sudo. Stops if Shuttle is running (ask the user to quit it first).
- **Linux with apt or dnf:** adds the signed package repository https://pkg.shuttlebrowser.com and installs the
  `shuttle` package (updates come with apt/dnf). Needs sudo. Without apt/dnf or sudo: the tarball into
  ~/.local/share/shuttle, command ~/.local/bin/shuttle.
- **sudo from an agent:** your shell usually can't answer a password prompt. If `sudo -n true` fails, ask the user to
  run the one-liner in their own terminal, or use `SHUTTLE_METHOD=tarball` (no sudo; needs libnss3 and libasound2).
- **Options:** environment variables for `bash`, not curl:
  `curl -fsSL https://get.shuttlebrowser.com | SHUTTLE_LAUNCH=yes bash`. `SHUTTLE_LAUNCH=ask|yes|no` (start Shuttle when done; without a terminal it only starts with
  `yes`), `SHUTTLE_METHOD=repo|tarball`, `SHUTTLE_CHANNEL=stable|testing`, `SHUTTLE_APPS_DIR=<dir>` (macOS).
- The script: https://github.com/shuttle-browser/shuttle/blob/main/tools/shuttle/assets/install.sh

**Windows:** Shuttle runs inside WSL2. Check with `wsl -l -v` (PowerShell). No version-2 distribution: the user runs
`wsl --install` in PowerShell as administrator and restarts Windows (you can't do that step for them). Then run the
one-liner inside Ubuntu. Shuttle shows up in the Windows Start menu. Agents on Windows and inside WSL both reach
`127.0.0.1:9222` (WSL forwards localhost). Lines about dbus, MESA or glx in the terminal are harmless.

**Manual install:** DMG https://www.shuttlebrowser.com/dl/Shuttle-0.1.3-arm64.dmg?via=site · .deb https://www.shuttlebrowser.com/dl/shuttle_0.1.3_amd64.deb?via=site · .rpm https://www.shuttlebrowser.com/dl/shuttle-0.1.3-1.x86_64.rpm?via=site · tarball https://www.shuttlebrowser.com/dl/shuttle-linux-x64.tar.xz?via=site
(all releases with SHA256SUMS: https://github.com/shuttle-browser/shuttle/releases/latest). Package repository by hand: https://www.shuttlebrowser.com/download

## Start and check

- macOS: `open -a Shuttle`
- Linux / WSL: `setsid -f shuttle >/dev/null 2>&1 </dev/null` (needs DISPLAY or WAYLAND_DISPLAY; not as root)

The installer's "Start Shuttle now?" (or `--shuttle-open-agents`) opens `chrome://agents`. Started without a terminal,
as above, Shuttle runs in the background without a window; the first agent tab opens one. Check that it's up (any
JSON-RPC reply means yes):

```bash
curl -s -X POST http://127.0.0.1:9222/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
```

If port 9222 was taken, Shuttle picks a free port: it's the first line of `DevToolsActivePort` in the profile directory
(macOS `~/Library/Application Support/Shuttle`, Linux `~/.config/shuttle`). Use that port in the URLs below.

## Connect

Add the MCP server named `shuttle` to the user's agent:

- Claude Code: `claude mcp add --transport http --scope user shuttle http://127.0.0.1:9222/mcp` (`--scope user`: all projects; leave it out for this project only)
- Codex: `codex mcp add shuttle --url http://127.0.0.1:9222/mcp`
- Cursor: in `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
  ```json
  {
    "mcpServers": {
      "shuttle": { "url": "http://127.0.0.1:9222/mcp" }
    }
  }
  ```
- Any other MCP client: a Streamable HTTP server with the URL `http://127.0.0.1:9222/mcp`.

Agents load MCP servers at startup: tell the user to restart their agent (a new session). The tools then show up under
the server `shuttle`.

## First task

Suggest this to the user after the restart:

> Use the Shuttle browser (MCP server "shuttle"): create an agent named "Scout", open a session, go to news.ycombinator.com and list the top 5 stories with their links. Close the session when you're done.

Flow for any task: `create-agent` once (pick a name, it keeps its logins), `open-session`, `allocate-tab`, then
`navigate-tab` and page tools (`snapshot` gives @eN refs for `click`, `fill`, ...), finally `release-tab` /
`close-session`. Reuse the same agent for the same sites so its logins persist.

## MCP tools

- `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.

Full docs: https://www.shuttlebrowser.com/docs

## Update and uninstall

- Update: macOS, run the installer again (quit Shuttle first). Linux: `sudo apt update && sudo apt upgrade` or
  `sudo dnf upgrade`; tarball installs, run the installer again.
- Uninstall, macOS: quit Shuttle, delete /Applications/Shuttle.app. Profile and agent logins:
  `~/Library/Application Support/Shuttle`.
- Uninstall, Linux: `sudo apt remove shuttle` (then delete /etc/apt/sources.list.d/shuttle.list and
  /etc/apt/keyrings/shuttle.gpg) or `sudo dnf remove shuttle` (then /etc/yum.repos.d/shuttle.repo). Tarball:
  delete ~/.local/share/shuttle and ~/.local/bin/shuttle. Profile and agent logins: `~/.config/shuttle`.
- Remove the MCP server from the agent: `claude mcp remove shuttle` / `codex mcp remove shuttle` / the Cursor entry.

## Links

Website https://www.shuttlebrowser.com · Download https://www.shuttlebrowser.com/download · Docs https://www.shuttlebrowser.com/docs · Comparison https://www.shuttlebrowser.com/why ·
Changelog https://www.shuttlebrowser.com/changelog · Issues https://github.com/shuttle-browser/shuttle/issues · Source https://github.com/shuttle-browser/shuttle