CARAPACE SETUP BOOTSTRAP — https://carapace.info/install
Revision: 2026-09-27. Release: 2026.09.27.1. Set up the owner's chosen runtime on their chosen host.
Success means a verified phone conversation, not just an installed service or QR.

1 — IDENTIFY THE TARGET; PRESERVE WHAT ALREADY WORKS.
The owner may use CARAPACE on iPhone while your tools run on a Mac or Linux host.
Identify target host, OS, runtime and existing installation with read-only tools.
The target runtime is the application, not its model: OpenClaw using Claude is
still OpenClaw, not a separate Claude Code install. Codex means Codex CLI.
An explicit runtime choice takes precedence over the installer agent's own
harness. Do not ask the owner to repeat it. If no target was chosen, use verified
runtime context; ask one short question only if the target remains ambiguous.
A binary or old configuration directory alone does not prove the target.

Do not impose elapsed-time turn limits or iteration budgets during setup.
Leave GW_TURN_CAP_MS and GW_TURN_STALL_KILL_MS unset. The Hermes connector
warns on lack of progress without killing work; verify /health reports
turnGuard.capMs=0 and turnGuard.stallKillMs=0. Treat Hermes config.yaml as
read-only: do not write agent.max_turns. Its default is unlimited (absent/null).
Flag a pre-existing finite limit for explicit owner review; never silently
replace an owner policy. A transport timeout is not proof the task stopped.

Use host tools for authorized work. Do not send phone users to desktop menus or
another CLI chat. Preserve working versions, native conversations, route keys,
account homes, tokens, permissions, models and custom supervisor configuration.
Never grant yourself access. Sign-in and OS/admin approvals belong to the owner
through the official private UI or masked entry, never through chat.

2 — CHOOSE ONE INSTALL PATH.
For Claude Code or Codex CLI, use the script at https://carapace.info/install.sh
with the target argument claude or codex. Other supported runtime arguments are
listed in the script; never derive the argument from a model name.
OpenClaw uses https://carapace.info/install/prompt/openclaw.md instead: OpenClaw
owns the runtime on 18789; CARAPACE adds the separate adapter on 18794. Preserve
an existing platform; do not run fresh onboarding over a working installation.
For a different supported runtime or manual recovery, use the matching document
listed at https://carapace.info/install/prompt/. Do not install multiple runtimes
unless requested.

Download to a new temporary file, not a reused file from a failed attempt:
  setup_file=$(mktemp /tmp/carapace-install.XXXXXX)
  curl -fSL --max-time 60 https://carapace.info/install.sh -o "$setup_file"
Require successful transport, HTTP 200 and a Bash shebang followed by the
carapace-install header. Read the complete script from disk, then run bash -n
on it. Never execute HTML, partial downloads, or an unchecked cached file.
For a manual, require the exact runtime heading, BEGIN PROMPT and END PROMPT;
read all relevant phases from disk without truncation before executing them.

If the download fails, report the URL and actual HTTP/transport result. A 403
does not prove the owner's machine is broken or healthy. A supported fetch tool
may retrieve the same public artifact; check its full bytes and runtime heading.
Never bypass authentication, disable TLS, invent mirrors, or execute a web page.
Install the complete dependency closure, not a copied server file from another
machine. OpenClaw and Claude gateways ship their nesting graph/transport and
Python ownership reader together. Follow https://carapace.info/install/ownership.md
for the external-launch capture step and its explicit limitations. Native Grok,
GPT or Claude models inside OpenClaw use its ordinary provider-independent child
relationships; a separately launched runtime requires explicit provenance.
The script verifies its bundle hashes. A hash match proves artifact consistency,
not runtime login or a successful turn.

3 — INSTALL OR UPDATE WITHIN THE OWNER'S AUTHORIZATION.
Read the detected changes before running. Explain the selected connection in
plain language: same-Wi-Fi LAN, private Tailscale, or public HTTPS. Preserve an
existing working route. Resolve new exposure/admin decisions only when needed.
Run the inspected script with its target argument; in agent/logged execution set
CARAPACE_PAIRING=defer so it cannot print a pairing credential into the transcript:
  CARAPACE_PAIRING=defer bash "$setup_file" claude
Use codex in place of claude for that target. This option is part of this release;
verify it exists in the downloaded script. Do not silently run an older script
without it. Manual installs render pairing only in an owner-private host surface.

A STOP prevents dependent steps. Diagnose its cause, retain completed work and
rerun after the cause is resolved; ask only for an actual missing owner decision
or authentication. Do not relay a long raw log or ask permission for every fix.
Updates must preserve custom settings, wait for active turns/pending decisions,
and identify the exact service plus the installer's own process ancestry before
a stop/reload. Never restart the gateway carrying this conversation. No reset,
re-pairing, model switch or global permission change is an installation repair.

4 — VERIFY THE RUNNING HOST, THEN PAIR PRIVATELY.
Verify the supervised listener and exact phone-facing route, not just loopback:
public health succeeds, unauthenticated protected access is refused, authenticated
access succeeds. Keep auth in the supported host-owned mechanism; never place
credentials in command arguments, shell variables, URLs, reports or chat.
Verify the chosen runtime is logged in as the intended account and its actual
runtime catalog is available. Do not promise Astra or any model from another
machine or an announcement; never invent an ID or silently substitute a model.

Use only the verified pairing helper or the OpenClaw manual's verified pairing
phase. Have it render in the owner's private host terminal/UI, outside tool logs
and chat. Never attach, paste, screenshot or read back its QR/link/token. If this
surface is unavailable, finish host checks and report PAIRING_PENDING with the
owner's local reprint action: ~/.carapace/bin/carapace-pair for script installs.
Do not repeat pairing or rotate a credential because a later chat check fails.

5 — ACCEPT THE EXPERIENCE, NOT JUST THE CONNECTION.
Verify a benign completed turn on an isolated test conversation, never the active
installing conversation; use the owner's chosen model and authorization.
SSE keepalives, tool events, accepted dispatch or partial text are not completion.
Do not resend an accepted timed-out request until exact history/run state shows
whether it completed. Keep test replies out of normal speech/Auto enrollment.

One growing assistant reply, with paragraph breaks: verify streaming AND reopened
history, a second separate turn, attachments, and interrupted partial text.
For a delivered file, verify it remains in finalized history after repeated
refreshes, reopening the conversation and an authorized idle adapter restart;
verify the same file bytes still download. On OpenClaw, persisted delivery
metadata must survive even when MEDIA directives are absent from saved text.
Never widen file access or expose hidden messages to recover an attachment.
Include a same-run/native-turn compaction continuation: verified checkpoints
must not split the reply; missing/conflicting identity, new user inputs and
unrelated internal handoffs must retain their boundaries. Use structured runtime
metadata, not matching prose, and preserve text, attachment order and reply ID.
On Codex the RUNNING gateway /health must advertise permissionsControl: "conversation-v1"
and replyGrouping: "turn-v1", locally and through the exact paired URL.
These markers are Codex-specific; test Claude, Hermes and OpenClaw behavior
independently. Do not suppress required progress updates to hide an adapter bug.
On OpenClaw, text must arrive as a steady stream during a tool-heavy turn, not in
lumps: a repeat /history read while the reply streams should take milliseconds.

Check exact session routes in the roster and picker. Preserve main conversations
even when old or unselected; informational groups are not selectable chats.
Do not hide every UUID lane, use emoji/title as identity, or confuse native
workspace discovery with OpenClaw's own lane. Build 544 or later requests typed nesting; older clients keep their lanes.
Verify a quiet live turn stays
active, then goes idle on completion; child work must not light the parent's
own-chat indicator. Keep activity timers continuous across app re-entry.
Phone checks are observable only on the phone: chat text, voice, cancel,
leave/reopen, and same-conversation selection. Record phone checks as passed,
failed or unobserved; do not claim an unattended host test observed the phone.

CODEX ACCESS, ONLY IF THE OWNER WANTS TO CHANGE IT.
Default: Ask for approval (workspace-write / on-request). With the verified
capability above, wait until idle; in the SAME Carapace Codex conversation the
owner can choose Full access after typing /permissions, then tap Answer.
It persists for that conversation and aliases; other conversations are unchanged.
The agent must not answer it. Host OS/admin protections still apply. Full access
allows files/network without Codex approval prompts and risks data loss/exposure.
To reverse it, choose Ask for approval through /permissions, then Answer.
Cancel changes nothing. Do not require Full access to pass installation.

HANDOFF — FOUR FACTS, NO SECRETS.
Report host/runtime; HOST_READY, PAIRING_PENDING, PHONE_CHECK_PENDING, VERIFIED,
or BLOCKED with the decisive evidence; what the owner can use now; and the single
remaining action if any. VERIFIED requires the completed runtime turn and actual
phone acceptance. Health, QR generation, upload, and tests alone cannot earn it.

OpenClaw's own Claude sessions: when OpenClaw runs a Claude model through its CLI
backend, every fresh backing session is a new native Claude transcript. This release
keeps those out of the Claude picker and nests them under the agent that ran them,
using the live process parent plus Claude's own per-process session record. Confirm
it on the running host with the checks in https://carapace.info/install/ownership.md
(section "Sessions launched by the OpenClaw gateway"), including its polling check: a
new session must never appear in the typed Claude picker, not even for a moment. Report the owner's reuse
rate if most Claude turns start a fresh session: that churn belongs to the platform.

External-child check: when the selected OpenClaw setup launches a separate Claude
process, read https://carapace.info/install/ownership.md before claiming nesting.
The owning platform must supply exact launch-time identity, including SDK init
and warm-turn capture. Reader installation or a legacy executable wrapper alone
is not capture. Run the fresh/warm/resume/visible-child/hidden-child matrix and an
independent Claude CLI negative control from ownership.md. Record installed,
loaded, live hierarchy and phone stages separately; queued is not durable.
Use EXTERNAL_OWNERSHIP_PENDING for an unsupported platform or lifecycle stage
and retain standalone access. Never overwrite resume state or change models.