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 and persisted

across extension service-worker eviction). 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 ``

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 `` content scripts. Permissions

are only what the debugger API (and a popup-pin context-menu entry) need

(`tabs`, `debugger`, `storage`, `alarms`, `contextMenus`).

• 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

The extension is not on PyPI — `pip install sallyport` (step 2) gives you

only the daemon. The extension lives in this repo's `extension/` directory, so

you need a checkout to build it:

git clone https://github.com/ginkida/sallyport
cd sallyport/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:

# Use the ABSOLUTE path. A GUI-launched Claude Code often doesn't inherit your
# shell PATH, so a bare "sallyport-daemon" command silently fails to spawn.
claude mcp add sallyport "$(which sallyport-daemon)"

`sallyport-daemon doctor` prints this exact line with the path already resolved

(and falls back to `python -m sallyport_daemon` if the console script isn't on

PATH) — copy it from there if you're unsure. The result:

{
  "mcpServers": {
    "sallyport": {
      "command": "/Users/you/.local/bin/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.

Several sessions, one browser (automatic)

Sallyport is built for the case where *you* are using Chrome while one or more

Claude Code sessions drive tabs in it. That works out of the box: the first

`sallyport-daemon` starts a small broker in the background and attaches to

it, and every session after that attaches to the same one. Register Sallyport as

in step 3 from as many project folders as you like — nothing else to set up.

# Nothing. Just start a second Claude Code session.

Under the hood the broker owns the extension connection and the port; each

session relays its MCP over a `0600` Unix-domain socket next to the secret

(`broker-10086.sock`). Before this, the second session simply failed to start —

the first one held the port — and had no browser tools at all.

What you get:

• Sessions don't block each other. Calls from different sessions run

concurrently (a session's own calls stay in order, and a tab is only ever

touched by one call at a time). One agent's 30-second wait no longer freezes

everyone else's next click.

• Each agent stays in its own tabs. An agent can only see and act on tabs it

created (`navigate` with no tab opens a fresh one); it cannot touch — or even

list — your tabs or another agent's. `list_tabs` shows a session only its own.

• It won't steal your focus. Each session's tabs live in its own un-focused,

muted window, and the window you were using is re-focused if Chrome tries to

raise the new one. Screenshots work there too, without foregrounding anything.

• You can see who did what. The popup's Audit tab tags every row with the

session (its folder name by default), and its Agent tabs section lists what

each session left open, with a one-click sweep.

• You're logged in. These are ordinary tabs in your real Chrome profile, so

agents operate on the sites you're already signed into — scoped, as always, to

the allowlist. There is no incognito or separate profile involved: the

separation is about *who may drive which tab*, not about identity.

Useful knobs:

sallyport-daemon --no-broker            # single session, own the port directly
                                        # (or SALLYPORT_NO_BROKER=1)
sallyport-daemon --session-label review # name this session in the audit log
sallyport-daemon broker --idle-exit 3600  # start one explicitly, exit when idle
sallyport-daemon doctor --stop-broker   # stop it (needed after an upgrade:
                                        # a broker outlives `pip install -U`
                                        # and serves its build to everyone)

The broker is long-lived by design, so `doctor` treats it as the intended setup

rather than a stale daemon: the port check reports OK, and

`doctor --kill-stale` leaves it running.

This is a *software partition* of one shared profile, not an OS-level sandbox:

the security floor is still "any process running as you" (it can read the secret

and drive the browser within the allowlist). See `SECURITY.md` for

the full model, including the tab-ownership and MCP-client-auth invariants.

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

> A running broker owns the port, so stop it first (`sallyport-daemon doctor

> --stop-broker`) or pass a different `--port` and update the popup's daemon URL.

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 key=value...` calls one tool and exits, printing

the result. 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` works alongside running Claude Code sessions: when a broker is up

(the normal case) it goes through it as a one-shot client rather than

fighting for the port. With no broker it owns the port itself, and is then

mutually exclusive with a running session — stop it, or pass a different

`--port` here and update the popup's daemon URL.

• Without a broker, 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 .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](https://semver.org/). 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.