CLI Bridge

cli-bridge — issue CLI bundles for the user's own starchild binary

This skill mints a fresh AKM key (scope=chat:bridge:cli) on the local clawd, then registers it with sc-chatroom in exchange for a short opaque code (`sc_xxxxxxxx`). The bundle handed to the user contains only that short code — never the AKM secret, never the Fly machine id.

+----------------+   POST /agent/chat/stream   +-----------------+
| starchild CLI  |   Bearer sc_xxxxxxxx        | sc-chatroom     |
| (user laptop)  | --------------------------> | (gateway)       |
+----------------+                             +--------+--------+
                                                        |
                            resolves sc_… → AKM + container_id
                                                        |
                                                        v
                                          POST /chat/stream (Bearer sk_…
                                          + fly-force-instance-id)
                                          +----------------------+
                                          | user's own clawd     |
                                          | (Fly internal)       |
                                          +----------------------+

Why a short code instead of the raw AKM?

Earlier versions baked the AKM secret + Fly machine id into the bundle directly. That worked but had two downsides — the bundle leaked routing metadata when decoded, and any party that ever held the bundle held a permanent AKM secret. The short-code form fixes both:

• Bundle base64 decodes to `{d, c:"", k:"sc_…", s, exp, l}` — no secret, no Fly machine id.
• `cli-revoke <sc_…> kills just the short code; the underlying AKM stays alive (use cli-revoke --akm <prefix>` to nuke that too).
• sc-chatroom now holds the AKM secret in its DB. That's a deliberate trust shift — the AKM stays inside Fly's internal network instead of riding around on user laptops.

Scope boundary — read this first

cli-bridge covers exactly one path: the user's local CLI talking 1:1 to that user's own clawd. It is not a chatroom membership credential.

Install the CLI

The rest of this skill assumes starchild is on the user's $PATH — install it first if it isn't.

One-liner (auto-detects OS + arch)

curl -fsSL https://workroom.iamstarchild.com/install/cli | bash

Picks the right binary for darwin/linux × arm64/amd64, drops it on $PATH (Apple Silicon lands in /opt/homebrew/bin; Linux falls back to ~/.local/bin; sudo only when the dir isn't user-writable), patches the user's shell rc if the install dir wasn't already on $PATH, and runs starchild --version as a self-check. SHA256 etag means re-running is a cheap "already current" no-op (HTTP 304, no download). Source for review: tools/install-cli.sh (__SERVER_URL__ is rewritten at request time).

Homebrew

brew tap starchild/tap https://github.com/Starchild-ai-agent/homebrew-tap
brew trust starchild/tap
brew install starchild

The starchild formula ships binaries for macOS (arm64 / amd64) and Linux (arm64 / amd64) — brew install picks the right one for the host. The formula has no bottle block, so install runs a tiny Ruby script that downloads the prebuilt binary from the server (workroom.iamstarchild.com) and drops it on $PATH — there's no local compile step. To upgrade later: brew update && brew upgrade starchild.

Linux caveat: Homebrew itself works on Linux, but expects a Ruby + build toolchain (one-time apt install build-essential ruby / distro equivalent). For a Linux host, the oneliner above skips that and is functionally identical, so prefer it unless the user is already a brew user. `starchild-app` (the desktop workspace) is macOS-only — that formula builds from source (rust + node) and only the macOS build is meaningful.

Verify

starchild --version

If you just ran the one-liner and your shell still says command not found, open a new terminal — the PATH update is in your rc, not the current session.

Prerequisites

Same as chatroom:

• AKM is installed in this clawd (POST /api/keys works on loopback)
• AKM accepts scope="chat:bridge:cli" and the /chat/stream middleware allows arbitrary thread_id for that scope (already shipped in clawd branch aladdin/feat/akm-chatroom)
• sc-chatroom is on a build that includes POST /cli-keys (migration 007+)
• FLY_MACHINE_ID (or CONTAINER_ID) env is set
• CHATROOM_PUBLIC_URL env points at the sc-chatroom gateway (defaults to https://workroom.iamstarchild.com)
• CHATROOM_SERVER_URL env points at the Fly-internal sc-chatroom (defaults to http://sc-chatroom.internal:8080)

Commands

cli-login — mint a new bundle

python3 skills/cli-bridge/scripts/cli_login.py --label "my laptop"
python3 skills/cli-bridge/scripts/cli_login.py --label "codex-vm" --ttl-days 14

Default TTL is 90 days; max is 365 days. Output is a one-liner the user copies into starchild login. The bundle is opaque — sc-chatroom resolves it on each call.

cli-list — show active bundles

python3 skills/cli-bridge/scripts/cli_list.py
python3 skills/cli-bridge/scripts/cli_list.py --include-revoked

Lists every CLI short code minted by this user on sc-chatroom. Columns: code, issued, expires, uses, label.

cli-revoke — kill a bundle

python3 skills/cli-bridge/scripts/cli_revoke.py sc_xxxxxxxx
python3 skills/cli-bridge/scripts/cli_revoke.py --akm sk_yyyyyy

Default: kills the short code in sc-chatroom; underlying AKM stays alive. With --akm: also revokes the AKM on local clawd, taking out every bundle backed by it.

Local shell via agent-shell (CLI ≥ v0.2.0)

A cli-login bundle minted with `--enable-shell` also authorizes the agent to run shell commands on the user's own machine — for "is nginx running on my laptop", "organize ~/Downloads", and the like. A plain bundle is a chat bridge only and grants no shell access (see "Shell is off by default" below). The user starts a small daemon:

starchild agent-shell            # daemonizes; holds a WS open to your clawd
starchild agent-shell --foreground   # attach to the terminal for debugging
starchild agent-shell-stop       # stop the daemon

agent-shell refuses to start if the logged-in bundle wasn't granted shell — it tells the user to get a --enable-shell bundle rather than connecting a channel clawd would reject.

The daemon is single-instance (pidfile + flock) and macOS/Linux only. It self-updates at startup and periodically; downloaded binaries are verified against an embedded Ed25519 release key before swapping, so a hostile or MITM'd update server can't push arbitrary code to the user's machine.

How it works: the daemon dials wss://<chatroom>/ws/cli-shell with the bundle's sc_… code. sc-chatroom resolves the code and reverse-proxies the WebSocket to the user's clawd machine — it accepts the laptop's upgrade, opens its own upstream WS to clawd pinned with fly-force-instance-id, and pumps bytes between the two (this is not fly-replay: chatroom and clawd are different Fly apps, and cross-app replay is rejected with 403). The AKM is injected server-side on the upstream hop — it never reaches the laptop. clawd holds the connection in its ShellHubService; the local_shell tool is then exposed to the LLM only while a shell-capable laptop is connected, and pushes commands down the socket.

Shell is off by default (capability gate)