Carapace

Getting Started

Carapace is a security-focused personal AI assistant that runs locally and connects through Signal, Telegram, Discord, Slack, webhooks, or console.

This guide covers first‑run setup, security basics, and day‑to‑day operations. It’s intentionally practical: copy/paste steps, then customize.

If you prefer outcome-first walkthroughs (for example "add Discord"), see the Cookbook. If you want the website flow instead of Markdown docs, start at https://getcara.io:

Prerequisites

Install options:

If you are starting from zero, optimize for a fast verified first outcome:

If you are still unsure which path fits your environment, use the Providers hub or Help page.

Run the interactive setup:

cara setup

Or skip the provider menu explicitly by choosing one provider:

# Choose ONE of these commands:
cara setup --provider anthropic
cara setup --provider openai
cara setup --provider codex
cara setup --provider ollama
cara setup --provider gemini --auth-mode api-key
cara setup --provider gemini --auth-mode oauth
cara setup --provider vertex
cara setup --provider nearai
cara setup --provider venice
cara setup --provider bedrock

To use the local Claude CLI provider, configure it directly in carapace.json5 using claude-cli:<model> in agents.defaults.model or a specific agent's model field. The setup wizard does not currently expose Claude CLI as a --provider option.

Migrating from another tool?

If you already have provider keys configured in OpenClaw, OpenCode, Aider, or NemoClaw, import them instead of re-entering manually:

cara import openclaw   # from ~/.openclaw/
cara import opencode   # from ~/.opencode.json
cara import aider      # from ~/.aider.conf.yml + .env
cara import nemoclaw   # from ~/.nemoclaw/config.json

Import shows a preview of what will be mapped and asks for confirmation before writing. Run cara verify afterward to validate the imported setup works.

Codex sign-in and Gemini --auth-mode oauth are interactive-only in the CLI. They launch a browser sign-in flow and complete through a loopback callback on a local port. The Control UI exposes the same Codex/Gemini onboarding choices if you prefer to do it in the browser. Both sign-in paths require CARAPACE_CONFIG_PASSWORD.

Then start Carapace:

cara

In another terminal:

cara verify --outcome auto --port 18789
cara verify --outcome autonomy --port 18789
cara status --port 18789
cara chat --port 18789

The setup wizard asks for:

If you picked a custom port in setup, use that instead of 18789. If your selected outcome is discord or telegram, cara verify may also need destination flags (--discord-to / --telegram-to). cara verify --outcome autonomy submits a real durable task and verifies it starts and reaches done/blocked.

Helpful REPL commands:

For full first-run flow, use site/first-run.md. Manual configuration is documented in config.example.json5.

Need guided help?

Configuration Basics

If you just want a working first run, you can skip this section and come back later.

Config is JSON5 and can live in:

See config.example.json5 and docs/protocol/config.md for all keys.

Secrets at Rest

If CARAPACE_CONFIG_PASSWORD is set, secrets at known paths are encrypted at rest using the current enc:v2 envelope (AES-256-GCM with Argon2id-derived keys). If the password is missing or wrong at startup, encrypted values are replaced with empty strings in the loaded config (the on-disk file is not modified). Unsupported older encrypted envelopes are rejected.

Session Encryption at Rest

Session history and metadata can be encrypted at rest via sessions.encryption.mode. When enabled with CARAPACE_CONFIG_PASSWORD, sessions are AES‑256‑GCM encrypted with .crypto-manifest recovery metadata. There is no in-place rekey — changing the password requires a fresh encrypted session store. See docs/protocol/config-reference.md for mode options.

Named Execution Routes

Instead of repeating provider:model strings across agents, define named routes once under the top-level routes map and reference them by name:

{
  "routes": {
    "fast":   { "model": "gemini:gemini-2.5-flash" },
    "strong": { "model": "anthropic:claude-sonnet-4-6" }
  },
  "agents": {
    "defaults": { "route": "fast" }
  }
}

See the named routes cookbook recipe for a full walkthrough.

Security Baseline

Minimum recommendations:

Auth Modes

"gateway": {
  "auth": {
    "mode": "token",   // or "password" or "none"
    "token": "..."
  }
}

mode = none is localhost only; remote requests are denied.

Control UI

Enable the Control UI:

{
  "gateway": {
    "controlUi": { "enabled": true }
  }
}

Then visit /ui on the Carapace host. You can override the base path via gateway.controlUi.basePath. If you are modifying the frontend assets, rebuild with ./scripts/build-control-ui.sh.

Hooks (Web API)

Hooks let external systems send messages through Carapace — useful for CI/CD notifications, monitoring alerts, or custom integrations. They are separate from service auth and require their own token.

{
  "gateway": {
    "hooks": {
      "enabled": true,
      "token": "${CARAPACE_HOOKS_TOKEN}"
    }
  }
}

See docs/protocol/http.md for request/response shapes.

Running Behind a Reverse Proxy

If you terminate TLS in a reverse proxy:

  1. Keep Carapace on localhost or a private network.
  2. Forward / to Carapace.
  3. Preserve request headers.
  4. Set gateway.trustedProxies to your proxy IPs so local‑direct detection works correctly.

Operations

Use the dedicated ops guide for day-2 workflows:

Most common commands:

cara status --port 18789
cara logs -n 200
cara backup --output ./carapace-backup.tar.gz
cara update

cara logs prints the last N log lines; it does not stream continuously.

Troubleshooting

If unsure, start with RUST_LOG=debug and inspect logs. For a structured checklist, use site/get-unstuck.md.