Recommended setup

Set up CARAPACE with one line.

Get the app, then say one line to the agent already running on your machine:

set this up: https://carapace.info/install

Your agent checks the runtime you want to control, preserves an existing setup, and installs the matching connection. It asks only for choices or sign-in that need you. Then pair privately on your host and check a real conversation on your phone.

1. Get the iPhone app 2. Copy the line
1

Download the app

Install CARAPACE from the App Store. Keep your phone ready for private pairing and a quick conversation check.

2

Say one line

Give carapace.info/install to the agent on the machine you want to control — Claude Code, Codex, OpenClaw, or Hermes. No long prompt to paste. It checks your chosen runtime and downloads the matching instructions.

3

Pair & verify

The agent verifies the host connection. Scan the QR from your private host display, then send a message and check voice and reopened history. Pairing alone is not the finish line.

Works with every runtime

Say this to your agent.

Reading this on your phone? You don’t need the clipboard — the line is short enough to type into your agent, or to say out loud. The instructions live at that URL, so the agent goes and gets them.

set this up: https://carapace.info/install

Paste it into Claude Code, Codex, OpenClaw, or Hermes on the machine you want to control. Nothing in it is a secret — every key is minted on your machine, for your phone only.

What your agent does next
  1. Opens the URL. It gets a concise setup checklist in plain text — no page to render, no buttons, just instructions written for an agent.
  2. Checks your chosen runtime. Claude Code, Codex CLI, OpenClaw, or Hermes — the harness it runs inside, not the model behind it. If it isn't sure, it asks you instead of guessing.
  3. Checks the installer. It downloads and inspects the correct script, preserving an existing setup. OpenClaw has its own platform-and-adapter path.
  4. Connects and verifies. Pair privately on the host, then check a real reply, voice, and conversation history on your phone. A working connection is only the first check.

Nothing hidden: read carapace.info/install yourself before you hand it over — it's the whole instruction sheet, in plain text. Every setup document also re-checks the runtime for itself before it changes anything, so an agent that grabbed the wrong file stops and fetches the right one.

Agent can't open links?

Some agents have no web tool, or sit behind a proxy that blocks the fetch. Paste the instructions inline instead — this says the same thing carapace.info/install says.

The same setup checklist as the URL above, including recovery and phone acceptance.

Know your runtime already?

Choose the runtime you want to control. Your installing agent can use a different runtime; it will preserve this choice.

Anthropic's coding agent. Paste the bootstrap into a Claude Code session on the target machine.

Keeps your explicit runtime choice throughout setup.
To inspect the complete maintenance reference: view the raw file · curl -fsSL https://carapace.info/install/prompt/claude.md
⚠️ The pairing QR / link is a key, not a picture.

Anyone who scans or opens it controls your gateway — every session, every file it can reach. Never post it, screenshot it, or share it. Keep it in your private host display, never in chat or logs. If it leaks, use the runtime's credential-recovery flow.

Codex permissions, from your iPhone

Codex starts with Ask for approval. On an updated gateway, wait for your current turn to finish, type /permissions in the same CARAPACE Codex conversation, choose Full access, then tap Answer. It applies to your next message and persists for that conversation; other conversations stay unchanged. No Terminal, desktop menu, or new chat needed.

Full access allows file changes and network commands without Codex approval prompts, with a risk of data loss or exposure. Your computer’s OS and administrator protections still apply. Send /permissions again and choose Ask for approval to reverse it; canceling changes nothing. Your agent must verify the running gateway supports this control before suggesting it, and must never choose access on your behalf.

Missing a model? Your host’s runtime, catalog and account determine what is available. A model announcement alone does not mean it is available in your conversation.

Connect your way

Setup detects where your machine lives and picks the safest shape it can prove — telling you which and why. It only asks when the answer is genuinely yours to make. No networking knowledge needed.

Home network (LAN)

Phone and computer on the same Wi-Fi — pair directly, nothing to install. Pairs over plain http://, so the gateway key crosses that Wi-Fi unencrypted: fine on a trusted home network, wrong for office or café Wi-Fi — choose Tailscale there.

Tailscale (recommended)

Private, encrypted, works from anywhere, and nothing is exposed to the internet. Setup installs it only if you say yes.

Your own HTTPS setup

Already run a reverse proxy or port forwarding? Setup detects it and pairs through it — your configuration stays yours.

Public server (VPS)

On a public IP setup arranges automatic HTTPS with a real certificate — and tells you exactly which ports it opens, before it opens them.

On a VPS: how it’s secured (from the installer’s own header)
  • The gateway binds 127.0.0.1 only — never a public interface, never a wildcard.
  • Authorization is a 256-bit token (file mode 0600 on the host). Pairing copies it to your phone, which sends it to your gateway with requests. Keep the QR and link private; use ~/.carapace/bin/carapace-pair --rotate if it leaks, then re-pair.
  • Public IP, no domain? It installs caddy, takes port 443, and serves https://<your-ip-with-dashes>.sslip.io with a real certificate — no DNS, no account, no cost. (That hostname derives from your IP, so it is public and appears in certificate-transparency logs.)
  • Automatic HTTPS installs caddy and may need administrator access. Missing prerequisites or Tailscale, if selected, can require other packages or host permissions. A Caddyfile you wrote is refused, never overwritten — if a proxy already owns 443, it stops and asks for its URL instead.
  • It survives reboots and closed SSH sessions (systemd + linger), and plain HTTP across the internet is never chosen automatically.
  • Needs: node ≥ 18 (it installs it for you when it has root) and curl.
Windows?

Run it inside WSL2 with systemd enabled (systemd=true in /etc/wsl.conf, then wsl --shutdown once) — and use Tailscale inside the distro: WSL2’s NAT means the LAN address it finds isn’t reachable from your phone.

Non-destructive by design

Inventory first

It detects your OS, runtime, network shape, and ports before touching anything.

Review before running

Your agent reads the installer and checks the scope with you when needed. The script runs without interactive prompts; it stops when a choice or missing permission needs your input.

Keep existing setup

Re-runs reuse pairing credentials and runtime state. Gateway and service files may be refreshed; your agent must check existing customizations and active work before an update.

Fails closed

Missing prerequisite, busy port, unprovable network path → it stops and asks, never improvises.

Your data is preserved

Existing agent auth, memory, history, and identity are never reset, deleted, or overwritten.

Optional, after pairing: bring your own voice provider (OpenAI, xAI/Grok, or ElevenLabs) with your own API key — in the app under Settings → Voice. You approve the data-sharing before anything is sent.