Deploy Rw

Deploy remote-workstreams

You are deploying remote-workstreams: a persistent launchd service on this Mac, reached from the user's iPhone over their tailnet. The end state is a running service, secrets in the Keychain, HTTPS on the Mac's MagicDNS name, and a phone paired via QR code. This skill runs the same from Claude Code or Codex — one deploy serves both engines.

Three helper scripts live in scripts/ next to this file. They print key=value lines and are all idempotent — re-running any of them is safe.

Rules

• Confirm before changing the system. Before every command that touches system state — git clone, Keychain writes, launchctl, tailscale serve, installing Tailscale — tell the user exactly what you will run and why, and get a yes. Read-only commands (check.sh, tailscale status, --help, curl of healthz) need no confirmation.
• Secrets: never echo stored secrets back, never write the plaintext PIN anywhere.
• Re-runs are normal. This flow doubles as repair: check.sh shows what is already done; skip completed steps unless the user wants to redo one (e.g. rotate a key).

Step 0 — Assess

Run scripts/check.sh [REPO_DIR] (default checks ~/remote-workstreams). Read the output and tell the user what is already in place and which steps remain. On a healthy install (everything ok/present/configured), say so and ask what they want to change.

Step 1 — Preflight: macOS, uv, tmux, service repo

• os=unsupported → stop; remote-workstreams runs on macOS only (launchd, Keychain, CoreAudio).

• uv=missing → have the user install uv (https://docs.astral.sh/uv/) and re-check.

• tmux=missing → tmux is a hard prerequisite: every agent session remote-workstreams drives lives in the voice tmux session. With the user's OK run brew install tmux (no Homebrew → https://brew.sh first), then re-run check.sh and confirm tmux=/tmux_version= report a binary.

• repo=missing → the service needs a durable git clone of remote-workstreams. Ask the user if they already have one (re-run check.sh THEIR_PATH to verify); otherwise, with their OK, clone the canonical remote to ~/remote-workstreams:

  git clone https://github.com/ryan-scheinberg/remote-workstreams ~/remote-workstreams
  

  Never run the service from the plugin's own marketplace clone — the host CLI replaces that directory on plugin updates.

Everywhere below, $REPO is the resolved repo path and $TS is the tailscale binary path printed by check.sh.

Step 2 — Engines

check.sh reports which agent CLIs exist (claude= / codex=) and whether Codex's role-skill symlinks are in place (codex_role_skills=). The service launches codex from launchd's Homebrew-aware PATH, so it follows the maintained CLI install without depending on the ChatGPT app bundle. At least one CLI must be installed and logged in. At runtime the model name carries the engine; three store settings shape what this box offers:

• engines — which engines the phone's picker shows (claude, codex, or both)
• planner_model / injector_model — who runs + Workstream and Send latest. The phone's PLANS menu row sets both from one pick and offers exactly opus (thinks at high) or gpt-5.6-luna (xhigh); seed one of those two so the row shows the selection (default opus; gpt-5.6-luna is the Codex equivalent)

Claude Code needs no wiring beyond login — the service hands its sessions the plugin directory at spawn. Wiring Codex is three symlinks (it discovers skills globally):

mkdir -p ~/.codex/skills
for s in role-convo role-stint-plan role-inject; do ln -sfn "$REPO/skills/$s" ~/.codex/skills/$s; done

Settings are written with this one-liner shape (add set_setting lines as needed; current model names live in remote_workstreams/engines.py):

(cd "$REPO" && uv run python -c "
from remote_workstreams.config import Config
from remote_workstreams.server.store import Store
store = Store(Config.load().db_path)
store.set_setting('engines', 'claude codex')")

Apply by what's installed:

• Both CLIs: ask the user whether to wire the second engine too, so both are pickable from the phone. Yes → the symlinks above and engines = claude codex; no → engines = the CLI you are running in. If you are running inside Codex, also set planner_model and injector_model to gpt-5.6-luna — the engine that installs drives the planning; the other stays pickable for conversation and workstreams.
• Claude Code only: set engines = claude. Defaults cover the rest.
• Codex only: the symlinks above, then engines = codex, planner_model and injector_model = gpt-5.6-luna, convo_model and workstream_model = gpt-5.6-terra so the first boot doesn't try to spawn a missing claude binary.

role_root=missing in check.sh → no role skill exists to launch workstreams with (see README); set store.set_setting('role_skill', '') so workstreams boot plain instead of typing a dead command.

All of it is an easy flip later — re-run this step after installing the other CLI.

Step 3 — Tailscale

• tailscale=missing → guide the install: download the Tailscale app from https://tailscale.com/download (or the Mac App Store), open it, and log in to their tailnet. Wait for the user to say it's done, then re-run check.sh. The app's CLI lives at /Applications/Tailscale.app/Contents/MacOS/Tailscale; check.sh finds it.
• tailscale_state must be Running — if not, have the user log in / toggle it on.
• Note the magicdns= name (e.g. mymac.tail1234.ts.net). It is the service's public name inside the tailnet; you need it in Steps 7–8. If it's empty, MagicDNS is off — the user enables it in the Tailscale admin console under DNS.

Step 4 — Provider API keys

For each of deepgram-api-key and cartesia-api-key that check.sh reports missing (or that the user wants to rotate): ask the user to paste the key (consoles: console.deepgram.com, play.cartesia.ai), then with their OK store it:

printf '%s' 'PASTED_KEY' | scripts/store_secret.sh deepgram-api-key

Same command shape for the other name. Keys go only to the login Keychain (service remote-workstreams, matching remote_workstreams/keychain.py) — never into files. There is no model API key: all model use rides the CLIs' own auth.

Step 5 — Pairing PIN

Skip if secret_pin-hash=present and the user isn't changing it. Changing the PIN does not invalidate paired devices — it only gates future pairings.

1. Ask the user to choose a 4-digit PIN (verify it matches ^[0-9]{4}$).
2. With their OK, store the hash only (the --hash flag runs the server's frozen remote_workstreams.server.auth.hash_secret — scrypt, salt voice-code-v1):

printf '%s' 'THE_PIN' | scripts/store_secret.sh pin-hash --hash "$REPO"

Note: 5 wrong PIN attempts lock pairing out for 10 minutes (server-side); a service restart also clears the lockout.

Step 6 — Install the launchd service

Tell the user this will run uv sync in $REPO, write ~/Library/LaunchAgents/com.remote-workstreams.server.plist (rendered from $REPO/deploy/com.remote-workstreams.server.plist.template), and launchctl bootstrap the service. With their OK:

scripts/install_service.sh "$REPO"

It fails fast if tmux is missing, then waits up to 30s for http://127.0.0.1:8400/healthz. On healthz=failed, read the log files named in the rendered plist, fix, and re-run the script.

At boot the service does the session bootstrapping itself — nothing to do here, but verify it took: it writes ~/.remote-workstreams/workstream-settings.json (per-boot approval hook wiring), creates the voice tmux session if absent, and spawns or resumes the persistent convo session in window voice:convo. A healthy check.sh therefore also shows tmux_session=voice and convo_window=alive; if either is off while healthz=ok, read the service logs — the tmux bootstrap failed.

Step 7 — Expose over the tailnet

tailscale serve puts HTTPS (real Let's Encrypt cert) on the MagicDNS name and proxies to the local service. The CLI syntax has changed across versions — run "$TS" serve --help first and adapt:

• Modern form: "$TS" serve --bg 8400
• Older form: "$TS" serve --bg --https=443 http://127.0.0.1:8400

Confirm with the user, run it, then verify: "$TS" serve status shows the mapping, and curl -fsS https://MAGICDNS_NAME/healthz succeeds. If serve complains that HTTPS is disabled for the tailnet, the user enables "HTTPS Certificates" in the Tailscale admin console (DNS page) and you retry. First cert issuance can take a minute.

Step 8 — Pair the phone

Print the pairing URL as a QR code plus plaintext:

(cd "$REPO" && uv run python -c "import qrcode; qr = qrcode.QRCode(border=1); qr.add_data('https://MAGICDNS_NAME/'); qr.print_ascii(invert=True)")

(Note: build a QRCode object — qrcode.make(...) returns an image with no print_ascii.) Then walk the user through it:

1. On the iPhone (on the same tailnet, Tailscale app connected), scan the QR or open the URL in Safari.
2. Share → Add to Home Screen, then open it from the Home Screen.
3. Tap Pair this device, enter the 4-digit PIN.
4. Approve the Face ID prompt (WebAuthn registration — the passkey is stored and used for every later unlock).

The phone now holds a passkey; every app open is one Face ID tap (Unlock). After a service upgrade that changed the credential schema, or a server restart, existing phones just Unlock again — re-pairing is only needed if the server says the passkey is no longer valid.

Step 9 — Final check and report

Run the audio round-trip test (synthesized speech in → transcript → reply audio out, uses the live keys):

(cd "$REPO" && uv run python -m remote_workstreams.audio.roundtrip)

Report pass/fail. Finish with a summary: service state, tmux session state (tmux_session= / convo_window= from a final check.sh), engines wired, MagicDNS URL, pairing status, round-trip result, and the rollback notes below.

Rollback / uninstall

• Stop the service: launchctl bootout gui/$(id -u)/com.remote-workstreams.server
• Roll back code: git -C "$REPO" checkout PREVIOUS_TAG, then re-run scripts/install_service.sh "$REPO"
• Stop serving: "$TS" serve reset (or the equivalent shown by "$TS" serve --help)
• Remove secrets: security delete-generic-password -s remote-workstreams -a NAME per entry
• Unwire Codex: rm -f ~/.codex/skills/role-convo ~/.codex/skills/role-stint-plan ~/.codex/skills/role-inject