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 ollama
cara setup --provider gemini --auth-mode api-key
cara setup --provider gemini --auth-mode oauth

--auth-mode oauth is interactive-only in the CLI. It launches a Google sign-in flow and completes through a loopback callback on a local port. The Control UI exposes the same Gemini onboarding choices if you prefer to do it in the browser. Gemini Google sign-in requires 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 (AES‑256‑GCM). 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).

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.