Set up CARAPACE with one prompt.

============================================================ CARAPACE + OPENCLAW SETUP — GUARDED, INVENTORY-FIRST, NON-DESTRUCTIVE Paste this entire message to a coding agent running ON the machine you want to set up (Mac, Linux, VPS, or Raspberry Pi). Agent: follow the phases in order. The user may be non-technical — explain blockers in plain language and never improvise around a missing prerequisite. ============================================================ PHASE 0 — GATES AND CONTRACT (read fully before any action) 0.1 Execution gate. FIRST, prove you can execute commands here: run `uname -a && echo CARAPACE_SHELL_OK` and show the real output. If you cannot actually run shell commands on the user's machine, STOP and say: "I can't execute commands here. Open a local coding agent (e.g. Claude Code) on the machine itself and paste this prompt there." Never simulate, imagine, or describe command output as if you had run it — anywhere in this setup. 0.2 Platform gate. Supported: macOS, Linux (incl. VPS), Raspberry Pi. If this is Windows: STOP — this prompt does not support Windows. 0.3 What you are setting up (two layers, installed in this order): • OpenClaw — agent gateway/runtime. CLI `openclaw`; gateway on 127.0.0.1:18789 (/health); config ~/.openclaw/openclaw.json; workspace ~/.openclaw/workspace (AGENTS.md, MEMORY.md, IDENTITY.md, PROJECTS.md, HEARTBEAT.md, BOOTSTRAP.md). • CARAPACE — status bridge ~/.carapace/status-server.js on 127.0.0.1:18794 (/health, /agents, /sessions, /projects, /history, /chat, /cron, /workorders, /loops, voice + /context endpoints), published to the user's iPhone over Tailscale Serve; the app pairs by QR (`carapace-qr`) on the SAME tailnet. • Loops — the user-facing operating and audit layer the iPhone app shows OVER the raw machinery. On current CARAPACE builds the bridge rolls cron jobs, work orders, evidence, health, and reusable modules up into one hierarchy of "loops" (read-only at /loops and /workorders), so the user can see whether the agent's recurring work is actually running and producing proof instead of reading raw cron rows. Loops sit ABOVE cron; they never replace it. An older bridge without /loops still works — the app shows the underlying cron and work-order views until it is updated. Port 18795 belonged to a retired legacy tracker: never configure, start, or route it; if you find remnants, report them (1.5). 0.4 The contract — five rules for this entire task: (a) INVENTORY BEFORE ANY MUTATION (Phase 1 touches nothing). (b) PROPOSED PLAN, then (c) APPROVAL GATE: the user must reply with explicit approval before ANY step that creates, edits, moves, installs, or restarts. Partial approval = do only that part. (d) ADDITIVE OVER REPLACEMENT: merge into existing config and use sentinel-bounded inserts; never wholesale-rewrite files, services, or Tailscale Serve state. (e) TIMESTAMPED BACKUP BEFORE EDITING ANY EXISTING ARTIFACT: <file>.bak.<YYYYMMDD-HHMMSS> (MEMORY.md uses .carapace.bak.<ts>). Applies to EVERYTHING you mutate: openclaw.json, AGENTS.md, MEMORY.md, status-server.js, any plist/systemd unit you overwrite, AND a snapshot of `tailscale serve status` to a timestamped file before any route change. 0.5 FAIL-CLOSED. STOP, explain plainly, and ask the user on any of: missing sudo/permissions; Tailscale absent or not logged in; no AI provider authed; no usable package manager; port 18789/18794 held by a process that is not our own OpenClaw/CARAPACE; any existing config you cannot unambiguously interpret; a Serve route you need is already owned by something that is not this stack; a needed system-scope service action requires sudo you lack. 0.6 NEVER, under any circumstance: reset OpenClaw; delete or wipe user data, auth, history, memory, or projects; restart services outside the explicit approved steps below. Restarts exist for exactly two reasons — first start, and loading approved changes — never to "retry harder" after a failed check. 0.7 Secrets. Never print, request, or accept secrets in this chat (API keys, gateway tokens, paired tokens). If a step needs one, tell the user the exact file or command where THEY enter it locally, wait, then verify presence only (e.g. via jq '… != ""') — never the value. 0.8 Artifacts. Official sources only: https://carapace.info (installer `install.sh` and status-server source) and the pinned GitHub repo it documents. To use one: download to a local file (`curl -fsSLo <file> <url>`), report URL + size + first lines to the user, include it in the Phase 2 plan, run only after approval. Never pipe network content directly into a shell; never fetch from anywhere else. The Mac installer is also the canonical behavior reference for the Mac path; on Linux/Pi you must DISCOVER service names from the live system, not assume them from the Mac layout. Two config tweaks in Phase 5 are CARAPACE-spec additions the stock installer does not perform. PHASE 1 — INVENTORY (read-only; mutate nothing) 1.1 System: `uname -a` (note arch); Mac `sw_vers` / Linux `cat /etc/os-release`; package manager (brew/apt-get/dnf); service manager (launchctl vs systemctl; note if neither — warn, not fail). Mac: note `id -u` for the launchd gui/<uid> domain. 1.2 OpenClaw: `openclaw --version`; `curl -sf http://127.0.0.1:18789/health`; locate openclaw.json and report WHICH of these keys exist (values never): gateway.requestTimeoutMs, gateway.trustedProxies, agents.defaults.bootstrapMaxChars, …bootstrapTotalMaxChars, provider/auth section. Gateway token PRESENCE only: `jq -e '.gateway.auth.token != null and .gateway.auth.token != ""' ~/.openclaw/openclaw.json`. Service discovery — record the REAL label/unit and its SCOPE: Mac: `launchctl list | grep -i openclaw` (commonly ai.openclaw.gateway) + its plist path. Linux/Pi: BOTH `systemctl --user list-units --all '*openclaw*'` AND `systemctl list-units --all '*openclaw*'` — record name AND scope (user vs system); do not assume either. Workspace: list ~/.openclaw/workspace — note which standard files exist. Providers: HOW MANY are configured and whether a fallback exists (count only). Note that memory/history/projects exist (presence only — this is user data you will protect). 1.3 CARAPACE: does ~/.carapace exist; status-server.js present (size/mtime, existing .bak files); `curl -sf http://127.0.0.1:18794/health` (cross-check /diag if ambiguous). Service discovery — BOTH scopes, same as 1.2: Mac: `launchctl print gui/$(id -u)/com.carapace.status-server`. Linux/Pi: `systemctl --user list-units --all '*carapace*'` AND `systemctl list-units --all '*carapace*'` — record unit AND scope. (Real installs exist where the bridge is a SYSTEM unit.) 1.4 Tailscale: `tailscale version`; `tailscale status` (logged in? which tailnet? do not dump the peer list); `tailscale serve status` — RECORD the full current route map (collision detection in Phase 7 and preservation depend on it). 1.5 Ports: `lsof -nP -iTCP:18789 -sTCP:LISTEN` and same for 18794 (`ss -ltnp` on Linux). Classify each: free / ours (which unit) / stranger (fail-closed). On Linux resolve PID→owning unit via `cat /proc/<pid>/cgroup` (.service slice), not the process name. Also check 18795 listeners and any serve route or unit mentioning 18795 — that is a retired legacy remnant: REPORT it, propose removal in the plan, never remove unasked. 1.6 Helpers: are `carapace-qr`, `carapace-onboard`, `carapace-prune` on PATH? 1.7 Topology question (ask the user, one line): "Do you already run CARAPACE on another machine on this tailnet?" If yes, confirm they intend a second host — the iPhone app pairs to one host at a time, and most users want exactly one controller. If this machine hosts unrelated production services, name them in the plan as a risk. 1.8 Print a concise INVENTORY REPORT: platform; gateway label/unit + scope; token present/absent; bridge health; serve route map; port owners; helpers; topology answers. ALREADY-HEALTHY SHORT-CIRCUIT: if gateway /health is OK, bridge /health is OK, the serve route map already contains the Phase 7 contract, the workspace sentinels (Phase 6) are present, and a provider is authed — say so, print the Phase 9 SETUP RECEIPT, and STOP. Offer fixes only if the user asks for a change. PHASE 2 — PROPOSED PLAN + APPROVAL GATE List ONLY the steps actually needed (skip what is satisfied — this whole procedure is idempotent and safe to re-run). For each step: exact file/command, why, the backup to be taken first, and (for service/serve actions) the discovered label/unit/scope or route it acts on. Group: prerequisites → OpenClaw → config tweaks → workspace files → bridge → Tailscale routes → verification → pairing. If the plan would publish the gateway root over Tailscale Serve (`https=443 /` → 127.0.0.1:18789), list it as its OWN confirmable line item: it exposes the gateway to the tailnet beyond the 18794 bridge; it matches the reference CARAPACE layout; the user may decline it and keep only the 18794 routes the iPhone needs. Surface every Phase 0.5 blocker here as a blocker — do not propose working around one. >>> STOP. Ask: "Reply 'approve' to proceed with exactly this plan, or tell me what to change." Do nothing further until approval. PHASE 3 — PREREQUISITES (only the unmet ones, after approval) 3.1 Package manager absent → STOP and ask; never auto-install one. 3.2 Node/runtime: install per platform only if OpenClaw needs it (Mac: brew node; Linux: distro node; nvm last resort). Sudo you lack → STOP. 3.3 Tailscale: if not installed / not up, STOP and have the USER install it and run `tailscale up` (it may need a browser auth flow), and confirm their iPhone's Tailscale app is signed into the SAME tailnet with Tailscale DNS on. Hard dependency — pairing cannot work without it. Never claim/auth a tailnet yourself. PHASE 4 — OPENCLAW (base layer) 4.1 Installed and 18789 /health OK → leave it alone. 4.2 Missing → install per the official reference (0.8 download rule), then start per platform: • Mac (first install only): `openclaw gateway install`, then `launchctl bootout gui/$(id -u)/<discovered-label>` (ignore errors) and `launchctl bootstrap gui/$(id -u) <plist>` — using the label discovered in 1.2 (back up any pre-existing plist first). This bootout/bootstrap ritual is for FIRST start only. • Linux/Pi: first install `systemctl [--user] enable --now <discovered-unit>` IN THE DISCOVERED SCOPE (`sudo systemctl` for a system unit — if that needs sudo you lack, STOP). `restart` is only for already-loaded units. No systemd → WARN, start by the documented manual method, record how. 4.3 After any start: poll `curl -sf http://127.0.0.1:18789/health` up to ~30s before continuing. 4.4 Provider auth: if NONE is configured, STOP and tell the user exactly what THEY do — Mac: the Carapace wizard's provider screen; Linux: `openclaw onboard` (or `carapace-onboard`); they enter the key there themselves (rule 0.7). Then re-verify presence. Exactly one provider → WARN there is no fallback; do not rewire providers. PHASE 5 — OPENCLAW CONFIG TWEAKS (additive; CARAPACE-spec) Back up openclaw.json first. Apply ONLY these, ONLY if lower/unset, preferring the CLI that owns the file over JSON surgery: 5.1 `openclaw config set gateway.requestTimeoutMs 180000` 5.2 `openclaw config set agents.defaults.bootstrapMaxChars 50000` and `… bootstrapTotalMaxChars 200000` 5.3 gateway.trustedProxies → MERGE IN (keep existing entries): "127.0.0.1", "::1", "100.64.0.0/10", "fd7a:115c:a1e0::/48" 5.4 Restart to load config, then wait for /health (~30s): • Mac: `openclaw gateway restart` (canonical config-restart; not the bootout ritual). • Linux/Pi: `systemctl [--user] restart <unit>` in the discovered scope. /health not back → STOP: restore openclaw.json from the backup, point at ~/.openclaw/logs, report. Do not loop restarts. PHASE 6 — WORKSPACE FILES (sentinel-bounded, non-destructive) All inserts use BEGIN/END sentinel blocks; if a block exists it is a NO-OP; never touch content outside markers. A file so hand-edited that no clean insert point exists → STOP and ask. 6.1 AGENTS.md (back up first): upsert the block bounded by `<!-- BEGIN CARAPACE VISION RULES` … `<!-- END CARAPACE VISION RULES -->`. If the workspace ALREADY carries equivalent rules — this block OR a maintained CARAPACE_RULES.md referenced from AGENTS.md — treat rules as installed; never create a second, divergent copy. 6.2 MEMORY.md (back up to .carapace.bak.<ts>): upsert the CARAPACE project-rules block and ensure `<!-- BEGIN CARAPACE PROJECTS -->` … `<!-- END CARAPACE PROJECTS -->` exists (the iOS Projects tab reads/writes there). DO NOT import old memory into it unless the user explicitly asks. 6.3 PROJECTS.md: create ONLY if missing; it must end with the literal sentinel line `<!-- carapace:initial-scan:done -->`. If the file exists, verify that exact sentinel is present (append it if not) and that no first-run "scan everything" instructions remain. Never run a memory/project scan yourself. 6.4 IDENTITY.md: exists and non-default → leave UNTOUCHED. 6.5 BOOTSTRAP.md: move to .bak.<ts> ONLY if it is ours (CARAPACE sentinel) or the stock openclaw template; otherwise leave it. Per- subagent BOOTSTRAP.md files are retired the same way (backup, then remove) — bootstrap is main-only. 6.6 HEARTBEAT.md: noisy legacy heartbeat → replace (after backup) with a quiet comments-only file; already quiet → no-op. PHASE 7 — CARAPACE BRIDGE (18794) + TAILSCALE ROUTES 7.1 Install/refresh ~/.carapace/status-server.js per rule 0.8 (official source, shown, approved), backing up any existing copy first; install its node deps as the reference does. Cannot confirm provenance → STOP. 7.2 Register and start the service IN THE DISCOVERED SCOPE, backing up any plist/unit you overwrite: • Mac: back up + write/refresh com.carapace.status-server plist; `launchctl bootout …` (ignore error) → `launchctl bootstrap gui/$(id -u) <plist>` → `launchctl enable …`. • Linux/Pi: back up + install/refresh the unit; first install `systemctl [--user] enable --now <unit>`, loaded unit `systemctl [--user] restart <unit>` — user vs `sudo systemctl` per the scope discovered in 1.3; missing sudo → STOP. No systemd → WARN and use the documented manual start. Poll `curl -sf http://127.0.0.1:18794/health` up to ~30s (/diag as fallback probe). Port 18794 held by a stranger → STOP (never kill it). RESTART-AFTER-UPGRADE RULE: if you replaced status-server.js (or OpenClaw itself was upgraded) on an already-running host, the old code keeps serving from memory until restarted — schedule exactly ONE restart for it in the approved plan, with backup + health wait. A repair without that restart has not actually shipped. 7.3 Tailscale Serve routes. FIRST snapshot shared state: `tailscale serve status > ~/.carapace/tailscale-serve.bak.<ts>.txt` (add --json variant if available). COLLISION CHECK against the snapshot: if `https=443 /` or any path you need points somewhere other than 127.0.0.1:18789 / 127.0.0.1:18794, STOP and ask. If the host already has the canonical contract script (`~/.openclaw/workspace/scripts/carapace-tailscale-serve-contract.sh`), prefer it: show it to the user, then run it (it re-applies the full current contract). NOTE: it begins with `tailscale serve reset` — only run it after the snapshot above and after the collision check found nothing foreign to preserve; otherwise fall through to additive route adds below. Otherwise add ONLY the missing routes (idempotent): • Bridge listener: `tailscale serve --bg --https=18794 http://127.0.0.1:18794` • Gateway root on 443 ONLY if confirmed in Phase 2: `tailscale serve --bg --https=443 http://127.0.0.1:18789` • iOS contract paths on 443 → the bridge, each via `tailscale serve --bg --https=443 --set-path /<path> http://127.0.0.1:18794/<path>`, covering at minimum: /health /identity /pair /status /agents /events /sse /sessions /chat /history /projects /cron /workorders /loops /tracker /context /cognitive /tts/convert /voice/last-unheard /voice/deliver /voice/mark-delivered (This list is the fallback copy and may lag the script — the script is the source of truth when present.) Confirm with `tailscale serve status` that intended routes are active AND nothing from the snapshot was removed or repointed. PHASE 8 — VERIFICATION + SETUP RECEIPT Run every check, then print EXACTLY this receipt shape (one line per check: PASS / FAIL(detail) / SKIP(reason)) and ALSO write it to ~/.carapace/setup-receipt-<YYYYMMDD-HHMM>.txt: ==== CARAPACE SETUP RECEIPT <date> ==== platform: <os/arch> · mode: <fresh|repair|already-healthy> gateway 18789 /health ............ PASS|FAIL bridge 18794 /health ............ PASS|FAIL tailscale up + tailnet ............ PASS|FAIL serve: :18794 listener ............ PASS|FAIL serve: 443 path set complete ...... PASS|FAIL (list any missing path) serve: 443 root → gateway ......... ADDED|DECLINED|PREEXISTING workspace files + sentinels ....... PASS|FAIL (per-file) PROJECTS.md scan sentinel ......... PASS|FAIL loops view (/loops) ............... PASS|SKIP(older bridge) gateway token present ............. PASS|FAIL (presence only) provider auth ..................... PASS|WARN single-provider|FAIL warmup chat reply ................. PASS|FAIL|SKIP(no provider) legacy 18795 remnants ............. NONE|REPORTED(detail) files changed: <each file → its backup path> serve snapshot: <path> warnings: <…> blockers: <none, or the single next user action> ==== END RECEIPT ==== Warmup chat = ONE short message through the bridge /chat or `openclaw` CLI, expecting a real non-error reply; skip when no provider is configured. PHASE 10 — IPHONE PAIRING + HANDOFF 10.1 Confirm the iPhone has Tailscale installed, signed into the SAME tailnet, DNS enabled — else STOP and have the user fix that. 10.2 Run `carapace-qr` and have the user scan it in the CARAPACE app; confirm agents/sessions/projects/chat load. 10.3 Tell the user their two next steps: voice setup (provider QR cards at https://carapace.info/install/voice/) and, if Tailscale is ever unavailable, the LAN fallback form http://<host>:18794 also works in the app's settings on the local network. 10.4 Final word = the receipt from Phase 9 (re-print if anything changed in Phase 10). If anything is blocked, state the single next action the user must take. If the user wants more than one agent, offer optional Phase 11 next. PHASE 11 — DEDICATED AGENTS (optional, recommended; do anytime the core stack from Phases 1-10 is healthy) A "dedicated agent" is a second (or third) OpenClaw agent with its OWN identity, history, projects, and purpose — for example one for a business, one for home/ops, one for research — kept separate from the main agent. In the iPhone app they appear in the agent switcher, and each agent's recurring work shows up as ITS OWN Loops, so the user can audit each area independently. Same contract as the rest of this setup: inventory first, propose, get explicit approval, back up, additive only — never reset, rename, or remove an existing agent. 11.1 Inventory (read-only). List the agents OpenClaw already knows from the agents section of ~/.openclaw/openclaw.json and the bridge's /agents (names + count only, never secrets). If the user has only the default agent and wants areas separated, propose dedicated agents; if they are happy with one agent, STOP — this phase is optional. 11.2 Discover the mechanism — do not assume it. Check `openclaw --help` and `openclaw agents --help` for the supported way THIS version adds and attaches an agent. Prefer the CLI or onboarding wizard that owns the config over hand-editing JSON. If this build has no agent subcommand, it manages agents through openclaw.json — back it up and STOP for approval before editing it. 11.3 Create on approval. For each agent the user approves: give it a clear name and a one-line purpose, and let OpenClaw create its ISOLATED workspace and identity (its own memory, projects, and history). Do NOT copy the main agent's memory or history into it unless the user explicitly asks. Back up openclaw.json first; add agents additively; one approval = only the agents named in it. 11.4 Attach + verify. Restart the gateway ONCE only if required to load the new agent (config-load restart, never "retry harder"), wait for 18789 /health, then confirm the agent now appears in the agents section of the config and on the bridge /agents. It shows in the iPhone app's agent switcher after a refresh. 11.5 How agents participate in Loops. Each dedicated agent OWNS its own recurring work — scheduled jobs (cron), work orders, and the evidence they produce — and the app rolls that up under that agent's Loops with health and proof. Give each agent only the loops it owns and keep one agent's scheduled work out of another's so the audit view stays honest per area. New scheduled work still goes through the same propose-and-approve gate as any other change; nothing here bypasses it. Re-print the Phase 9 receipt with an added line per new agent (name · purpose · /agents PASS · loops PASS|SKIP). ============================================================