Carapace

Getting Started

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, use:

Prerequisites

If you want to build from source, see CONTRIBUTING.md.

Install cara (Pre-Built Binary)

Download from the latest release: https://github.com/puremachinery/carapace/releases

Common artifacts:

macOS/Linux install:

chmod +x ./cara-<your-platform>
sudo mv ./cara-<your-platform> /usr/local/bin/cara
cara --help

Windows install (PowerShell):

$installDir = "$env:LOCALAPPDATA\cara\bin"
New-Item -ItemType Directory -Force -Path $installDir | Out-Null
Copy-Item .\cara-x86_64-windows.exe (Join-Path $installDir "cara.exe")
cara --help

Quick Start (Local, Token Auth)

Create a minimal config (save as carapace.json5) for either platform:

{
  "gateway": {
    "auth": { "mode": "token", "token": "${CARAPACE_GATEWAY_TOKEN}" }
  },
  "openai": {
    "apiKey": "${OPENAI_API_KEY}"
  }
}

macOS/Linux

export CARAPACE_GATEWAY_TOKEN="$(openssl rand -hex 32)"
CARAPACE_CONFIG_PATH=./carapace.json5 cara

In another terminal:

cara status --host 127.0.0.1 --port 18789
curl -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" http://localhost:18789/health
cara chat

Windows (PowerShell)

$bytes = [byte[]]::new(32)
[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
$env:CARAPACE_GATEWAY_TOKEN = [System.BitConverter]::ToString($bytes).Replace('-', '').ToLower()

$env:CARAPACE_CONFIG_PATH = ".\\carapace.json5"
cara

In another PowerShell terminal:

cara status --host 127.0.0.1 --port 18789
curl.exe -H "Authorization: Bearer $env:CARAPACE_GATEWAY_TOKEN" http://127.0.0.1:18789/health
cara chat

Expected /health response:

{ "status": "ok", "version": "x.y.z", "uptimeSeconds": 12 }

If you set gateway.port, use that port instead of 18789.

Helpful REPL commands:

Configuration Basics

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, encrypted values are scrubbed on load.

Security Baseline

Minimum recommendations:

Auth Modes

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

mode = none is local‑direct only (loopback); remote requests are denied.

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.

Hooks (Web API)

Hooks are separate from service auth and require a hooks token.

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

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

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.

Operations

Health Checks

Logs

Use the CLI:

cara logs --follow

Backups

cara backup --out ./carapace-backup.tar.gz
cara restore --path ./carapace-backup.tar.gz

Update

cara update

Troubleshooting

If unsure, start with RUST_LOG=debug and inspect logs.