Deckhand

Ask Claude for your app on any device — get a link.

Deckhand is an MCP server that runs on a Mac. Connect it to Claude (claude.ai, Claude Code, Routines — any MCP client) and ask:

"Test the onboarding screens on iOS 26 and Android 14 for PR #42"

You get back one calm page showing every device live, with full touch control — shareable publicly or behind a PIN. Claude can also see and drive the devices itself (screenshot, accessibility tree, tap/type) before it hands you the link.

For humans: set up Deckhand with an agent

Tell your coding agent:

Set up Deckhand on this Mac from https://github.com/Okam-AS/deckhand. Guide me step by step through the Cloudflare tunnel setup. When it is ready, give me the MCP connector URL and a pairing code so I can connect my agent.

Related MCP server: mobile-device-mcp

How it works

1. You ask — Claude calls start_preview with an app id, a ref/PR, and devices.

2. Deckhand builds — checks out the branch into a worktree (or builds a registered local checkout in place), builds once per platform, installs on every device.

3. Devices boot in parallel — iOS simulators via simctl, Android emulators via avdmanager/adb.

4. You get a link — a stable per-app share URL streaming all devices live, riding a Cloudflare tunnel. No VPN, no WebRTC, no TURN — if a network can reach claude.ai, it can view and control a preview.

Architecture

One Node process owns everything. Nothing but cloudflared is reachable from outside the machine.

 claude.ai / Claude Code / any MCP client      share-link viewers (any browser)
        │ HTTPS                                        │ HTTPS/WSS
        └───────────────────┬──────────────────────────┘
                            ▼
          cloudflared named tunnel → http://127.0.0.1:4300
                            │
┌───────────────────────────▼── deckhand server (loopback only) ──┐
│                                                                 │
│  /mcp                    MCP tools, bearer-authenticated        │
│  /oauth/*                per-client sign-in (pairing code)      │
│  /s/<shareId>            viewer page (device grid + controls)   │
│  /s/<shareId>/dev/<id>/* scoped proxy → that device's stream    │
│                                                                 │
│  auth → mcp tools → preview engine → devices → streaming        │
│           │             │               │          │            │
│       audit log    git worktrees    simctl /   serve-sim (iOS)  │
│                    + build recipes  adb        screenrecord     │
│                                                (Android)        │
└─────────────────────────────────────────────────────────────────┘

 on-disk: ~/.deckhand/{config.yaml, apps.yaml, tokens.yaml, oauth.json, state.json, audit.jsonl}

Building blocks

Stack: Node ≥ 22, TypeScript, ESM. No database, no SPA framework beyond the one viewer page, a ruthlessly short dependency list.

Two ways to run an app

• Git mode — Deckhand clones the repo, fetches any ref or PR into a detached worktree, and builds there. Fully self-contained.

• Local mode (daily dev loop) — register an existing checkout with deckhand app add <id> --path <dir>. Built in place, never mutated: Deckhand reads the checkout's git state but never writes to it. restart_preview (or the viewer's Rebuild button) rebuilds on the same booted devices.

Security model

• Everything binds loopback; the only way in is the Cloudflare named tunnel.

• Nothing that touches a device or a repo is reachable without a credential: a per-client MCP credential (an OAuth grant, or a local bearer token), per-app share links (optionally PIN-gated). The OAuth discovery, registration and sign-in endpoints are open by construction — a client with no credential has to start somewhere — and grant nothing on their own: a request that reaches them needs a pairing code minted on the Mac with deckhand pair.

• The MCP surface is capability-bounded — no arbitrary commands, only pre-registered apps and their repos' refs. Every call lands in an append-only audit log.

• Secrets never travel through MCP; tokens never appear in argv, URLs, or logs.

PLAN.md describes what the system is — architecture, the MCP surface, the security model; background knowledge in docs/reference/.

Install it

Hand an agent this repo URL and it can do most of it. Two things it cannot, and they are both yours: a Cloudflare login (a browser and your account) and a hostname on a domain you own.

git clone https://github.com/Okam-AS/deckhand && cd deckhand
npm install
npm run build                                   # viewer + landing
npx tsx server/src/cli.ts setup                 # ← run this first, with no arguments

With no arguments, setup checks the machine and prints exactly what is missing and who can fix it — the things it can install itself, and the things it needs you for. Do those, then run it again with your hostname:

If the preflight asked for cloudflared tunnel login, run that yourself first — it opens a browser and needs your own Cloudflare account, so it is the one step nothing here can do for you. Then:

npx tsx server/src/cli.ts setup \
  --hostname deckhand.yourdomain.com \
  --web-host previews.yourdomain.com            # optional, for web previews

If you are the agent

• Run setup with no arguments first. It labels every line with who acts, and fix: is the only one of the four you may run:

  • fix: — yours to run.

  • you: — a fix only a person at this Mac can do (an App Store install, an Apple ID, a sudo licence accept, the machine's default Node). Relay the line as written and stop; re-run setup once they say it is done.

  • BLOCKED — also relay-and-stop, but an errand off this machine: a browser and their Cloudflare account. Never attempt it — cloudflared tunnel login opens a browser and will hang you forever.

  • ASK THE USER — questions to ask in the words given, not a report to paste at them. There is more than one: a fresh install asks for the hostname and, marked (optional), a second hostname for web previews.

• Install what it says you can install. Then ask the user for a hostname on a domain they have on Cloudflare, and run setup --hostname <that> — adding --web-host <the second> if they wanted web previews.

• At the end, run deckhand pair yourself and give the user the code it prints; they type it into the page Claude opens. Typing the command is yours, typing the code into their own browser is theirs.

• Xcode is a ~10 GB App Store download needing an Apple ID and a sudo licence accept. Ask; do not claim to have done it.

• Android is optional. Without it, iOS previews work and Android does not — doctor says so as a warning rather than a failure.

setup creates the Cloudflare tunnel and DNS route, merges your cloudflared config (rules for other services are carried through the merge, and the previous file is copied to config.yml.bak before anything is written — so the one case the merge cannot preserve, a config.yml that will not parse and so comes back as nothing to merge with, is still recoverable by hand), links deckhand onto your PATH, writes deckhand's config, prints your connector URL, installs the LaunchAgents so it survives sleep and reboot, and runs doctor.

Re-run it any time: every step reports what it found and changes only what is missing, so it doubles as a repair tool.

Then register something to preview:

deckhand app add myapp --path /abs/path/to/a/checkout    # local — no GitHub needed
deckhand app add myapp github.com/owner/repo             # from git
deckhand doctor --device-only                            # boots a real sim + emulator

Then paste your connector URL into claude.ai → Settings → Connectors:

deckhand token          # prints https://<your-hostname>/mcp

The URL is not a credential. In a Claude team or Enterprise organisation a connector is visible to everyone in it, so deckhand puts no secret in the URL — and admits nobody because they have it. Clicking Connect opens a page that ASKS for a pairing code — and the only place one exists is your Mac:

deckhand pair                      # mint a code; type it into the page Claude opens
deckhand connections               # who holds a grant now
deckhand revoke <client-id>        # take it back, effective next call, no restart

A colleague who pastes the same URL is asked for a code they do not have. Nothing waits, nothing queues, and there is no list for a stranger to fill — the code exists only on your machine, for ten minutes, for one use.

Claude Code on the same Mac has no browser to sign in with, so it uses a local credential instead: deckhand token add <name>, sent as an Authorization: Bearer header. That one is a password — token list shows which exist with the values masked, token url <name> prints one in full, and token rm <name> revokes it on the running server.