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)

cli-login does not grant shell unless --enable-shell is passed. The AKM is the authoritative capability source: clawd reads it on the /ws/cli-shell handshake and refuses every exec for a connection that doesn't carry shell (#264). So a leaked plain bundle is a chat credential, never local RCE.

• Grant shell: cli_login.py --label … --enable-shell → AKM capabilities: ["shell"], bundle carries x: ["shell"].
• Upgrade an existing no-shell bundle: you can't flip it in place — mint a new --enable-shell bundle, starchild login it, and cli-revoke the old one. Privilege escalation always goes through a fresh issuance.

What the agent knows up front (capability manifest)

On connect, the daemon sends a hello frame advertising:

• Platform — os (darwin/linux), arch (arm64/amd64), and the active shell. So the agent knows whether it's talking to BSD or GNU userland, which package manager to assume, etc. — no more guessing ps flags or hitting ps: illegal option.
• Policy summary — mode (default-deny when no allow rules exist, else allowlist), the user's allowed rules, explicit denied_extra rules, and the always-on builtin_denied list.
• File-transfer policy — the transfer_dir (always-allowed workspace), yolo flag, and the read_allow / write_allow globs from ~/.config/starchild/file-policy.toml. Present only when the bundle carries the files capability. See "File path policy" below for the full rules; this bullet is just so the agent knows the laptop advertised file transfer at all.

clawd renders this into the agent's system prompt (only while connected), so the agent picks a permitted command — or tells the user plainly that the local policy forbids it — instead of probing blindly.

Session behavior

• Connection-level cwd. Each command's resulting working directory is echoed back (via a trailing-pwd sentinel stripped from stdout) and persisted for the next command, so cd has real meaning across calls within a session — without the cost/fragility of a full PTY. An explicit per-call cwd overrides it.
• Output truncation. stdout/stderr are each capped at 200 lines (plus a byte cap) so a find / or log dump can't flood the LLM context. The full pre-truncation line count is reported (stdout_lines / stderr_lines), and truncated: true is set — the agent can say "showing first 200 of N lines" rather than truncating silently.
• Heartbeat. The daemon pings every 45s to keep the idle WebSocket alive (Fly's edge cuts idle sockets at ~2.5min). Exec runs in a goroutine so a long command doesn't block heartbeats.

Local execution policy (the only auto-run guard)

The daemon runs headless (no TTY to prompt on), so every command is gated by ~/.config/starchild/exec-policy.toml (parsed as a tiny YAML allow:/deny: line format — no TOML dependency, despite the name). Rules are substring matches by default; wrap a rule in / / for a regex:

allow:
  - "ls"
  - "cat "
  - "/^git (status|log|diff)/"
  - "ps"
deny:
  - "git push"

Decision order: built-in deny (always wins) → file deny → file allow → default-deny. Two hard rules apply regardless of the file:

• A built-in deny list of interactive/TTY-blocking and destructive commands is always refused: vim/vi/nano/emacs, less/more/man, top/htop/btop, ssh/telnet, sudo/su/ doas, tmux/screen, reboot/shutdown/halt, plus the shapes rm -rf, mkfs, dd if=, … | sh, … | bash, > /dev/sd*.
• Default-deny: anything not matched by an allow rule is denied. So with no policy file the policy mode is default-deny and nothing runs until the user opts commands in.

Limitations

• Unattended policy only. There is no interactive approval prompt; the policy file is the sole guard. A future version adds a web-approval popup.
• Synchronous commands only. No background jobs / progress polling yet.
• macOS/Linux only. The daemon refuses to run on Windows.
• Revocation: cli-revoke <sc_…> kills the short code; the daemon's next reconnect then fails auth and the channel closes.

File transfer via agent-shell (CLI ≥ v0.3.0)

When the bundle is minted with --enable-files, the same agent-shell daemon also serves file transfer between the user's machine and the agent's workspace. Content streams disk→disk and never passes through the chat, so large/binary files (10MB+ PDFs, images, archives) work.

Three agent-facing tools + one user command:

• request_upload(laptop_path) — agent pulls a file FROM the laptop into workspace/uploads/ ("take my ~/big.pdf and summarize it").
• write_local_file(src, dst) — agent sends a workspace file TO the laptop ("save workspace/output/report.pdf to my ~/Downloads"). src is a workspace path, not inline content.
• read_local_file(path) — read a small text file for the agent to see (config/log snippet). Large/binary files go through request_upload.
• starchild push <file> — user proactively uploads a local file into the agent's workspace/uploads/; it's announced to the agent in its prompt.

python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-files
# combine with shell if you want both:
python3 skills/cli-bridge/scripts/cli_login.py --label "laptop" --enable-shell --enable-files

files is an independent capability from shell — a bundle can have either, both, or neither. Like shell, it's off by default and authoritative on the AKM (clawd refuses transfer frames for a connection without it).

File path policy (laptop-side, layered)

Transfers are gated on the laptop by a path policy, strictest-first:

1. Built-in protected paths are ALWAYS refused (even under --yolo): ~/.ssh, ~/.aws, shell rc (.zshrc/.bashrc/…), .config/starchild, launchd/systemd/cron, .git/hooks, browser cookie stores, .env, ssh keys. Writing those would be persistent RCE; reading them leaks creds.

2. Dedicated transfer dir (~/starchild-transfer, auto-created) — always allowed for read + write. The safe default workspace; prefer it.

3. Outside that dir — denied unless the path matches a read_allow / write_allow glob in ~/.config/starchild/file-policy.toml, or the daemon was started with --yolo:

   starchild agent-shell --yolo   # allow ANY path (built-in deny still applies)
   

   Copy

   # ~/.config/starchild/file-policy.toml  (YAML allow-globs)
   read_allow:
     - "~/Documents/*.md"
   write_allow:
     - "~/exports/*.csv"
   

   Copy

Other guarantees: written files get mode 0644 (never executable); writes are atomic (temp file + rename, no half-written target); symlinks that escape the transfer dir are refused; per-transfer cap is 100 MiB, streamed in chunks so large files don't blow the WS frame limit.

Security note: a running agent-shell (on a --enable-shell bundle) plus a permissive policy is effectively remote command execution on the user's machine, bounded by the AKM TTL, the sc_… code's validity, and the policy file. Defaults are conservative: shell is off unless explicitly granted, the policy is deny-all until commands are opted in, and the daemon's self-update verifies an Ed25519 signature before swapping binaries. Widen deliberately.

Local MCP servers via agent-shell (CLI ≥ v0.5.32)

agent-shell is the MCP Host for the user's machine. The same daemon that runs local_shell and file transfer also reads ~/.config/starchild/mcp-servers.toml, spawns each enabled stdio MCP server as a long-lived child process, runs the MCP initialize → tools/list handshake, and proxies tools/call over the existing WebSocket to clawd. clawd then registers each remote tool as mcp__<server>__<tool> and injects them into the current conversation — no new session is required.

This is the path for driving a LOCAL app (Blender, Godot, a local Figma-bridge, computer-use, browser-use, the filesystem server, …) from the cloud agent. The agent can't reach localhost on the user's machine any other way; clawd's own (direct) MCP support is for REMOTE/HTTP/SSE servers hosted elsewhere, not for processes that must run on the user's laptop.

How it works (the control channel is the same WS as local_shell)

clawd (cloud agent)
  │  mcp_list / mcp_call frames
  │  (over the existing /ws/cli-shell WebSocket)
  ▼
agent-shell daemon (laptop) ── MCPProxy
  │  stdio JSON-RPC (newline-delimited)
  ▼
blender-mcp / figma-mcp / server-everything / … (one process per server)

The laptop side owns the MCP session state (initialize → initialized → tools/list, cached). clawd only sends high-level mcp_calls; it never speaks raw JSON-RPC. A tools/list_changed notification from a server re-fetches and re-registers that server's tools.

Configuring a server

Edit ~/.config/starchild/mcp-servers.toml (YAML, despite the .toml extension — same convention as exec/file-policy). Each entry:

servers:
  - id: blender
    command: uv
    args:
      - "--directory"
      - "/Users/aladdin/Workspace/StarChild/blender_mcp/mcp"
      - "run"
      - "blender-mcp"
    env:
      - "SOME_KEY=value"
    enabled: true

Absolute paths only. $HOME and ~ are NOT expanded — MCP clients spawn the command directly, not through a shell. Use /Users/<name>/..., never ~/... or $HOME/....

enabled defaults to true (an entry without enabled: runs). The file is hot-reloadable, but running sessions only change when the daemon restarts — a reload updates the parsed config, it does not spawn/kill server processes mid-session. The app's Settings panel writes this file and restarts agent-shell for you.

Restarting agent-shell does NOT cut the chat

The chat stream (your reply to the user) runs over clawd's HTTP/SSE path, NOT over agent-shell. Restarting agent-shell only interrupts local_shell / file-transfer / mcp_call for the ~2s it takes to reconnect — the conversation itself stays alive. So you CAN tell the user (or do it yourself via local_shell) to restart the daemon after a config change; you won't kill the conversation.

After restart, the daemon sends a fresh hello with an mcp_manifest listing the enabled servers + each one's runtime status (ready/failed/not_started). clawd eagerly mcp_lists each ready one and registers the tools. A per-turn maybe_resync_local_mcp catch-up also covers servers that failed to fetch at hello (e.g. a slow-to-start server) on subsequent turns.

Dynamic injection — local_mcp_status + local_mcp_reload

You don't have to restart agent-shell to pick up a config edit. Two agent-facing tools drive the local MCP runtime live:

• local_mcp_status — returns every configured server's runtime state (ready with tool count, failed with the error, or not_started). Call this when an expected mcp__<server>__* tool is missing — the server may have failed to start.
• local_mcp_reload — asks agent-shell to re-read mcp-servers.toml at runtime, start newly-added servers, stop removed ones. No daemon restart, no chat interruption. After a reload, the added servers' mcp__<server>__* tools appear in the next turn (the tool list is rebuilt per request). Use this after editing the config to make a new server available without asking the user to restart anything.

Typical flow when a server the user just configured isn't showing tools:

1. Call local_mcp_status → see blender: not_started or failed: ….
2. (Fix the config if failed — bad path, missing dep, etc.)
3. Call local_mcp_reload → agent-shell starts the new server.
4. Next turn, mcp__blender__* tools are registered.

What the agent sees

• Tools appear as mcp__<server>__<tool> (e.g. mcp__blender__get_scene, mcp__everything__echo). Their description and input_schema come from the server's own tools/list — call them like any native tool.
• The prompt manifest (build_mcp_manifest_section, in the volatile tail) lists which local MCP servers are connected and a roster of their tool names. If a server is configured but failed to start, that is noted here too (config present, not loaded).
• If you don't see an mcp__<server>__* tool you expected, the server didn't come up. Diagnose in this order:
  1. Is it in ~/.config/starchild/mcp-servers.toml with enabled: true?
  2. Did agent-shell restart AFTER the edit? (config is read at start)
  3. The daemon log (~/.starchild/sc-chatroom[-dev]/cli-shell/agent.log) has a line per server: agent-shell: mcp: <id> ready (N tools) on success, or agent-shell: mcp: failed to start <id>: <reason> on failure. Read it via local_shell.
  4. For servers that need a LOCAL app bridge (Blender's addon on 127.0.0.1:9876, a Figma plugin, …) confirm that bridge is running too — the MCP server process can start but its tools will error until the backend app is reachable.

Don't bypass MCP to talk to the local app

When a server like Blender's is slow to register, it's tempting to open a raw socket to the app's own bridge (127.0.0.1:9876) and send Python directly. Don't — that sidesteps the MCP tool layer (no schema, no policy, no per-call validation) and the agent loses the structured mcp__blender__* interface. Fix the MCP server's startup instead (check the log, confirm the bridge, restart agent-shell). The raw bridge is a last-resort fallback only.

Server caveats (per-backend)

• Blender MCP (blender-mcp): two parts — the stdio MCP server (uv run) AND the Blender addon's bridge (listen on 127.0.0.1:9876). Both must be running. The MCP server starts even if Blender is closed, but every tool call errors until the addon bridge is up. which blender often fails even when Blender.app is open — that's fine, the bridge is what matters.
• Figma: there are TWO different Figma MCPs. figma-mcp-server (REST-wrapper, read-only canvas) runs locally via bunx; the official Figma remote MCP (write canvas, SSE) is a REMOTE server — configure it on the clawd side (mcp_servers: in agent.yaml), NOT here. This file is only for servers that run on the laptop.
• computer-use / browser-use: inherently local (they drive the user's screen/browser). Configure them here.

Security

A local MCP server can execute arbitrary code on the user's machine (Blender's execute_code, a shell server, …). Treat adding an entry to mcp-servers.toml with the same gravity as widening the exec policy: only add servers the user asked for, prefer read-only servers, and never put a secret (API key) in chat — use the env: field. The mcp-servers.toml path is NOT in the file-policy allow-list by default; add it there if the user wants the agent to write configs directly.

End-to-end smoke test

# 1. Inside agent chat:
@agent give me a cli key for my laptop
# → outputs `starchild login starchild_<base64>` (bundle has sc_… code)

# 2. On laptop:
starchild login starchild_xxx
starchild whoami
starchild "hello, who are you?"
# → starchild sends Bearer sc_… to sc-chatroom; sc-chatroom resolves
# → it to AKM + container_id and forwards to user's clawd

# 3. Revoke the short code from chat:
@agent revoke cli code sc_xxxxxxxx

# 4. Next CLI call should fail at the gateway:
starchild "hello?"
# → "gateway rejected (401) — code may be revoked; ask your agent for a fresh CLI bundle"

Pipe / shell composition (CLI ≥ v0.1.0)

Once paired, starchild is pipe-friendly. It reads stdin when no positional prompt is given, writes the assistant reply to stdout, and sends diagnostics to stderr — so it composes with any Unix tool.

# stdin → reply
echo "explain monads in 3 lines" | starchild

# reply → downstream
starchild "what is the OWASP top 10?" | pbcopy

# full three-stage pipe with streaming output
( echo "summarize this README:"; cat README.md ) | starchild --stream | tee summary.md

# code review pattern — concatenate context + question upstream
( echo "review this diff, flag risky changes:"; git diff ) | starchild

Gotcha: when you pass a positional prompt, stdin is ignored. To send both context and an instruction, concatenate them upstream with ( echo "<question>"; cat <file> ) rather than relying on cat <file> | starchild "<question>" (which would silently drop the file contents).

SOUL.md hint (recommended)

Add to your agent's SOUL.md so the LLM picks the right tool when the user asks for a CLI key:

## Issuing CLI bundles for the user's own bots/scripts

When the user asks "give me a cli key" / "create a starchild bundle" /
"let me talk to you from my terminal", run:

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>"

This is a chat bridge only — it does NOT let you run commands on their
machine or touch their files. Two independent opt-in capabilities, each
granting local access — only add them when the user explicitly asks:

- `--enable-shell` → run commands ("run commands on my laptop", "use
  agent-shell", "organize my Downloads"). Remote command execution.
- `--enable-files` → read/write files ("save this to my laptop", "read my
  ~/notes.md"). Reads/writes files on their machine.

  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-shell
  python3 skills/cli-bridge/scripts/cli_login.py --label "<inferred>" --enable-files

Treat both as granting access to their machine — never add either by
default or "to be helpful". If they later want a capability, mint a new
bundle with the flag and have them revoke the old one.

Default the label to something like "untitled-YYYY-MM-DD" if the user
doesn't suggest one. Show them the resulting bundle and tell them how
to revoke: `cli-list` to find the code, then `cli-revoke sc_…`.

After pairing, mention they can also pipe into the CLI from their
shell — e.g. `echo "..." | starchild`, `starchild "..." | pbcopy`,
or `( echo "review:"; git diff ) | starchild`. Stdout is the reply
(pipe-safe), stderr is diagnostics. Note the gotcha: passing a
positional prompt makes stdin get ignored, so context + question
should be concatenated upstream.

## Driving a local app via MCP (agent-shell ≥ v0.5.32)

Once `--enable-shell` is granted and `agent-shell` is running, you can
also drive LOCAL apps (Blender, Godot, a local Figma-bridge,
computer-use, …) through stdio MCP servers. The agent-shell daemon IS
the MCP Host: it reads `~/.config/starchild/mcp-servers.toml`, spawns
the servers, and registers their tools as `mcp__<server>__<tool>` into
this conversation. No separate MCP client (Cursor/Claude Desktop) is
needed.

When the user asks "control Blender" / "use the local figma plugin" /
"drive my local <app> via MCP":
- Confirm `agent-shell` is connected (a `local_shell` call works).
- Add the server to `~/.config/starchild/mcp-servers.toml` (ABSOLUTE
  paths only — no `$HOME`, no `~`). The app's Settings → Local MCP
  Servers panel can do this too.
- Restart `agent-shell` (`starchild agent-shell-stop && starchild
  agent-shell`, or via the app's RestartBanner). This does NOT cut the
  chat — only `local_shell`/file-transfer pause for ~2s.
- After restart the `mcp__<server>__*` tools appear. If they don't,
  read the daemon log (`~/.starchild/sc-chatroom[-dev]/cli-shell/
  agent.log` — look for `mcp: <id> ready` or `mcp: failed to start
  <id>: <reason>`) via `local_shell`.
- For servers with a local app bridge (Blender's addon on
  127.0.0.1:9876), confirm that bridge is running too — the MCP server
  process can start but its tools error until the backend app is up.
- Prefer the `mcp__<server>__*` tools over opening a raw socket to the
  app's bridge. The MCP layer gives you schemas + validation; the raw
  bridge is a last-resort fallback.

Don't add a server the user didn't ask for — a local MCP server can
execute arbitrary code on their machine. See the "Local MCP servers via
agent-shell" section above for the full config format and per-backend
caveats (Blender two-part, Figma local-vs-remote, etc.).