Sallyport

A secure browser-automation bridge between Claude Code (or any MCP client) and
your Chrome. An alternative to Kimi WebBridge with explicit security
boundaries instead of implicit ones.

Claude Code ── MCP/stdio ──▶ daemon ── WS+HMAC ──▶ extension ── CDP ──▶ Chrome

What's in the box

Security model

A deeper threat model + known limitations lives in SECURITY.md.
The short version: the original Kimi extension trusts any process that can
reach 127.0.0.1:10086, which on a shared/compromised machine means
everything. Sallyport changes the default in five places:

1. HMAC-SHA256 on every frame. A 32-byte random secret lives in
   ~/.config/sallyport/secret (chmod 600) and is generated on first run. Both
   sides sign every WS frame and verify timestamp drift (≤ 30 s) and nonce
   freshness (rolling cache of 4096 nonces — replay-protected). A
   cross-language test pin in pytest + vitest guarantees the canonical-JSON
   and MAC bytes stay byte-for-byte compatible.
2. Domain allowlist enforced in the extension. Tools refuse to run on any
   URL whose host isn't in chrome.storage.local.sallyport_allowlist. Patterns
   are example.com, *.example.com, or https://x.com/path/*. Bare * is
   rejected by the validator.
3. evaluate is opt-in per domain. Even on an allow-listed domain,
   arbitrary JS is refused unless that entry has allowEvaluate: true. Other
   tools (click, fill, read_text, …) use structured CDP calls only.
4. Defense-in-depth on inputs. fill refuses <input type=password>
   unless allowPassword=true. The daemon refuses to bind to anything that
   isn't a loopback address. WS frames over 16 MiB are dropped (1009).
5. Operational visibility. Every tool call (and its outcome — ok or
   error) is appended to chrome.storage.local.sallyport_audit (last 500
   entries), browsable and JSON-exportable from the popup. One-click Pause
   in the popup stops the WS connection and rejects all tool calls.

Other deliberate choices:

• No content-script injection, no <all_urls> content scripts. Permissions
  are only what the debugger API needs (tabs, activeTab, debugger,
  storage, alarms).
• Per-tab accessibility refs (@e1, @e2). Snapshotting tab A cannot
  invalidate refs for tab B, and a ref scoped to A cannot resolve to a node
  in B.
• MCP-side tool calls are serialised by a daemon-side lock so Claude can't
  accidentally race state on the extension.
• The daemon shuts down cleanly on stdin EOF (Claude Code closing) or
  SIGINT/SIGTERM: pending calls fail with ExtensionNotConnected, the
  client gets a 1001 close, no orphan tasks.

What the extension still trusts: anyone with read access to
~/.config/sallyport/secret. The browser debugger is, ultimately, the browser
debugger — this bridge limits which domains it operates on and who can
drive it.

Setup

1. Build the extension

cd extension
npm install
npm run build

The output lands in extension/dist/. Load it as an unpacked extension:

1. chrome://extensions
2. Enable Developer mode
3. Load unpacked → pick extension/dist

Pin the toolbar icon.

2. Install the daemon

Sallyport needs Python ≥ 3.10 (it uses match statements and X | Y type
syntax). Check with python --version first.

pip install --user sallyport

Or from source (for development): cd daemon && pip install --user -e .

This installs the sallyport-daemon command on your PATH. Verify it landed there:

which sallyport-daemon   # should print a path; if not, add your Python
                      # user-scripts dir (e.g. ~/.local/bin) to PATH

The first time something runs it, the daemon will:

• Generate a 32-byte secret in ~/.config/sallyport/secret (chmod 600).
• Print the base64 secret to stderr — paste it into the extension popup.
• Start listening on 127.0.0.1:10086 and speak MCP on stdio.

Then run the built-in setup check, which validates the install and prints the
exact block to paste into the popup:

sallyport-daemon doctor

It checks your Python version, the secret file and its permissions, and that
the port is free — then prints the pairing secret and the remaining steps.
Run it any time a connection won't come up. To just re-print the secret:

sallyport-daemon --show-secret

3. Register with Claude Code

Add an MCP server entry — either edit ~/.claude/mcp.json directly, or:

claude mcp add sallyport sallyport-daemon

Producing:

{
  "mcpServers": {
    "sallyport": {
      "command": "sallyport-daemon",
      "args": []
    }
  }
}

Restart Claude Code. The tools appear as mcp__sallyport__navigate,
mcp__sallyport__click, etc.

4. Pair the extension

1. Open the popup. It will show a one-card Pair onboarding view.
2. Get the secret. Run sallyport-daemon doctor (or --show-secret) in a
   terminal and copy the printed block. Note: when Claude Code spawns the
   daemon for you (step 3), the first-run banner goes to the daemon's stderr,
   which Claude Code does not display — so doctor/--show-secret is the
   reliable way to see it.
3. Paste into the popup textarea — you can paste the whole banner; the
   popup auto-extracts the base64 secret and shows
   "✓ secret detected (32 bytes)".
4. Click Pair. Status flips to connected with a pulsing green
   indicator and an at-a-glance summary of allowed sites / recent calls.

5. Add the first domain to the allowlist

The allowlist starts empty — every tool rejects every URL by default. In the
popup's Allowlist tab, add an entry like example.com or
*.github.com. Tick allow evaluate() only if you actually need
arbitrary JS on that host.

Tools

All tools accept tabId to target a specific tab; otherwise they use the
active tab in the current window. There is no implicit "last touched tab"
memo — explicit IDs win, the active tab is the only fallback.

For agents running on a schedule, the cheap iteration shape is: status
(skip everything if the extension is detached) → scoped reads
(snapshot selector=… compact=true, read_text ref=…) → actions with
embedded waitFor instead of separate wait_for calls → verify with
get_state ref=… (one element) instead of re-snapshotting the whole page.
Driven tabs are
kept awake automatically, so the loop keeps working while the browser
window sits in the background (see Troubleshooting for the trade-offs).

Compared to Kimi WebBridge

Sallyport implements the everyday Kimi tools (navigate, click, fill,
snapshot, screenshot, evaluate, mouse_click, upload, …) and adds
a few of its own (fetch_in_page, save_to_file, reload). Three Kimi
features are deliberately not here:

find_tab is also intentionally absent: Sallyport's list_tabs returns the
full set and the agent filters client-side — one round trip instead of two.

Testing it locally

Three layers, from fastest to most realistic:

A. Wire only — no MCP, no Claude Code

Confirms HMAC pairing, allowlist, audit log without any tools firing.

# terminal: run the daemon in WS-only mode. Stays up until Ctrl-C —
# no stdin / no MCP client needed.
sallyport-daemon serve

Default sallyport-daemon (no subcommand) expects an MCP client on stdin and
exits immediately on EOF — fine for Claude Code, awkward for local testing.
Use serve whenever you want a stable long-running daemon.

Open the popup → Pair → paste secret → status flips to connected.
That alone proves: WS reach, HMAC handshake, perms.

B. Fire individual tools from the shell — no Claude Code

sallyport-daemon exec <tool> key=value... spins up the daemon, waits for the
extension, calls one tool, prints JSON, exits. Values are JSON when
parseable, otherwise strings.

# Catalogue of tools (works offline, no extension needed):
sallyport-daemon list-tools

# Open a tab (the host must already be in the popup's allowlist):
sallyport-daemon exec navigate url=https://example.com newTab=true

# Read the page:
sallyport-daemon exec read_text

# Get the accessibility tree + refs:
sallyport-daemon exec snapshot

# Click something from snapshot (use a ref):
sallyport-daemon exec click selector=@e3

# Targeted screenshot:
sallyport-daemon exec screenshot format=jpeg quality=70

Notes:

• exec mode is mutually exclusive with the Claude Code MCP session
  (single-client invariant in the WS server). Stop Claude Code first, or
  pass a different --port here and update the popup's daemon URL.
• The first exec waits up to 10s (--wait 30 to bump it) for the popup
  to connect. Once paired, the extension reconnects on its own.
• Screenshot blobs are truncated in the printout — they're still passed
  in full to a real MCP client.

C. End-to-end with Claude Code

Once A and B work, register the MCP server (see Setup → step 3), restart
Claude Code, and ask it to do anything web-shaped. Watch the popup's
Audit tab — every call lands there with ok/error and target URL.

Troubleshooting

Rotating the secret

1. rm ~/.config/sallyport/secret
2. Restart whatever runs sallyport-daemon (Claude Code will respawn it on next call). A new secret prints to stderr.
3. In the popup: Unpair → paste new secret → Pair.

Development

# Extension
cd extension
npm install
npm run watch         # esbuild rebuild on save — reload extension in chrome://extensions to pick up
npm run typecheck     # tsc --noEmit
npm test              # vitest run
npm run lint          # eslint
npm run format        # prettier --write
npm run format:check  # prettier --check (CI gate)

# Daemon
cd daemon
pip install -e '.[dev]'
ruff check .
mypy
pytest -q
sallyport-daemon --verbose < <(sleep 99999)   # smoke-test a long-running daemon

Pre-commit

pip install --user pre-commit
pre-commit install

This runs trailing-whitespace/json/yaml/merge-conflict checks plus ruff, mypy,
prettier, eslint, and tsc on each commit. Heavy test suites stay in CI
because they're too slow for a commit gate.

CI

.github/workflows/ci.yml matrices over Python 3.10/3.11/3.12 (daemon) and
Node 20/22 (extension), runs lint + typecheck + tests + build for both, and
uploads extension/dist as an artefact on main.

Adding a new tool

Five files, same order both for an extension-side tool and a daemon-local
one — keep tool names byte-identical on both sides since routing is a dict
lookup.

1. Implement. Extension-side: a new extension/src/tools/<name>.ts
   exporting a Tool. Pure validators (path / arg shape) belong in a
   chrome-free sibling module like upload-path.ts so vitest can cover
   them without a chrome harness. Daemon-only: a coroutine in
   daemon/src/sallyport_daemon/local_tools.py registered in LOCAL_TOOLS.
2. Register on the extension side. Add an import + entry to the tools
   map in extension/src/tools.ts.
3. Declare the MCP schema. Append a Tool(name=..., description=..., inputSchema=...) to TOOLS in daemon/src/sallyport_daemon/mcp_server.py.
   Mark fields required whenever the implementation throws without them —
   schema and behaviour should agree (see the close_tab regression
   captured by test_close_tab_requires_tab_id).
4. Pin the catalogue. Add the new name to the expected set in
   daemon/tests/test_mcp_server.py::test_tools_catalogue_covers_extension.
   Mismatches between the daemon and extension registries fail the build
   immediately rather than at the wire.
5. Document. A row in the Tools table in README.md, and an entry in
   CHANGELOG.md under [Unreleased] / Added describing the user-visible
   shape (args, gates, error codes worth knowing).

Then cd extension && npm test && npm run lint && npm run typecheck
and cd daemon && ruff check . && mypy && pytest -q — all green before
calling it done.

Versioning & releases

CHANGELOG.md tracks every notable change; the project uses
Semantic Versioning. The wire protocol version is
1 — bump only on incompatible changes and update the cross-language
vector tests in the same commit.

License

MIT — see LICENSE.

Wire protocol

Documented in extension/src/protocol.ts and
daemon/src/sallyport_daemon/protocol.py. Envelope shape:

{ v, ts, nonce, type, id?, body, mac }

mac = HMAC-SHA256(secret, canonical_json({v, ts, nonce, type, id?, body})),
base64. Canonical JSON: keys sorted by Unicode code point, no whitespace,
unicode passthrough, cross-language number formatting.

The exact bytes are pinned to 49 cross-language vectors in
fixtures/canonical-vectors.json — both daemon/tests/test_vectors.py
and extension/test/vectors.test.ts read that file and assert byte-by-byte
agreement. If you change the canonicalisation rules, regenerate via
python3 fixtures/generate.py and update both implementations in the
same commit.

There is no version negotiation — both sides expect v: 1. Bump it on
breaking changes and update both vector tests in the same commit.