Connection help

The QR code didn’t appear

Claude Code, Codex or Hermes

If the line ended before its QR, run ~/.local/bin/carapace pair in a private terminal: on a Mac its login terminal, not SSH; on Linux a terminal window or an SSH login.

Type your phone’s six-digit code at the computer, and on a Mac approve with Touch ID or the login password. The agent must not answer these human checks.

OpenClaw

Codes expire in a few minutes. Run the OpenClaw line again for a fresh one. If the QR is not ready, see It asks to turn on TLS.

My iPhone needs pairing again

OpenClaw

When your iPhone needs approving again, or CARAPACE says it can't show questions from your computer (then first remove this computer in CARAPACE), run that line again: answer y if it asks whether to pair your iPhone again, then scan its new code and give the one yes. Removing the computer in CARAPACE also unpairs Claude Code and Codex there; paste the full line again to pair them.

If it ends saying an earlier request from your iPhone was still waiting, close CARAPACE on your iPhone, wait 5 minutes, then run it again.

Add another agent

Some runtimes only, with no runtime question: put their names after the line.

The names are claude, codex, openclaw and, on a Mac, hermes. Names only add: what CARAPACE already has stays.

Or paste the plain line again and choose Add a runtime. The line keeps your earlier answers in ~/.carapace-direct/install-answers and asks only about runtimes new on your computer. Finish active turns first: an update restarts the helper.

It didn’t find my agent

The agent must already be installed and signed in on this computer.

Set up its own way? CLAUDE_CONFIG_DIR or CODEX_HOME set to a full path in your shell is the folder that runtime keeps its sign-in in. A command the line does not find is named on bash’s side of the pipe, with that runtime’s name after the line:

Set up OpenClaw only

The line sets OpenClaw up when you add it. To set up OpenClaw alone: in a private terminal on your computer, run curl -fsSL https://carapace.info/install.sh | bash -s openclaw.

No helper is installed: OpenClaw pairs with your iPhone directly. The line asks OpenClaw for one limited pairing code (openclaw qr --limited) after checking encrypted transport.

Scan the code. The setup waits for your iPhone’s request, shows it with the first characters of its fingerprint, approves exactly that one after your yes, and ends there. If your iPhone does not connect, scan the same code again. Press Return to stop waiting.

Codes expire in a few minutes; rerun the setup line if one expires.

It asks to turn on TLS for OpenClaw

For a stock loopback or old plaintext LAN setup, the line asks before enabling native TLS and LAN access; OpenClaw generates its certificate and reloads when safe. This needs the matching secure-pairing TestFlight build of CARAPACE, not an older app.

If the QR is not ready, do not turn TLS off: let OpenClaw become idle and run the line again. Do not reset pairings or install a certificate on your phone.

Use it away from home

Home Wi-Fi works at home; it is not remote access. Away from home, use your existing Tailscale network, or for OpenClaw your own secured HTTPS endpoint or an existing Tailscale Serve connection. Tailscale is optional.

Setup does not install Tailscale, create public ingress, change proxy trust or install another connector, and the helper does not configure Tailscale or a public relay. Existing HTTPS/Tailscale settings stay unchanged; old CARAPACE paths on your Tailscale address that lead nowhere are removed only after your yes.

Custom addresses need a dedicated OpenClaw Gateway origin, not a proxy subpath or an inference API. Re-pair deliberately if the certificate or address changes.

Update CARAPACE on my computer

Finish active turns, then paste the line again: it stops CARAPACE, updates, and starts it again.

Keep native logins, paired phones and history; do not purge state to fix a connection.

I lost my phone or shared a code

OpenClaw

For OpenClaw, in a private terminal: review the paired devices, reject a pending request you do not want, and remove that phone.

Generate a fresh limited code only in your private terminal. Never share codes or credentials in support messages.

Claude Code, Codex or Hermes

In a terminal on your computer, list paired phones, then revoke the lost one by its id or name; its connections are closed.

What does the helper need?

The helper needs Linux or macOS 13.5 or later, and the runtime already installed and signed in; it brings its own Node.js. Linux: with systemd, as your normal user (no sudo); so far tested on Ubuntu 24.04 in a virtual machine only, without a phone. It does not run on Windows, and Hermes is offered on a Mac only.

Phone turns use your own Claude Code or Codex sign-in on your computer, under your own plan.

Let my assistant set it up

Tell the assistant on your computer:

You still scan, type the code and approve yourself. No code appears on this website.

Run it with no questions

Run without a terminal, or as curl -fsSL https://carapace.info/install.sh | bash -s -- --no-questions, it asks nothing, adds every signed-in Claude Code and Codex it finds (and Hermes on a Mac), and its last line starts with CARAPACE:; the next time you paste it at the computer it asks once whether to keep them. curl -fsSL https://carapace.info/install.sh | bash -s -- --json prints each install's result.

I’d rather not pipe into bash

This longer line saves the script to a file, runs it, then deletes it, and keeps curl to https even if the address were ever redirected.

It says connected, but nothing happens

A connected indicator is not a completed conversation. Check a typed reply, Stop, voice, reopened history, files both ways and a photo separately.

Direct OpenClaw currently has smaller file limits than the classic connection. A custom voice needs your own compatible server.