First Run

Outcome

Run cara setup, start Carapace, and complete your first useful assistant workflow.

Prerequisites

• cara installed: Install guide
• One supported provider configured:
  • ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, or VENICE_API_KEY, or
  • local Ollama (OLLAMA_BASE_URL)

0) Pick the simplest first path

If you are not sure where to start:

• choose local-chat as your first outcome
• start with one provider only
• use Anthropic/OpenAI for the fastest cloud path, or Ollama for the fastest fully local path
• add Discord, Telegram, or hooks only after cara verify --outcome auto passes

If provider choice is the blocker, use the Providers hub. If you want a maintainer to help you pick the shortest path, use Help.

1) Run the setup wizard

cara setup

The wizard walks you through:

• provider + API key (with optional credential validation),
• gateway auth mode (token/password) and strong-secret generation,
• bind + port,
• first-run outcome:
  • local-chat
  • discord
  • telegram
  • hooks
• optional hooks token and Control UI toggle.

Today that interactive path writes Anthropic/OpenAI first-run config. If neither ANTHROPIC_API_KEY nor OPENAI_API_KEY is set and Carapace detects Ollama, Gemini, Venice, or a full Bedrock env set, cara setup will stop and point you to the provider/help path before it writes the wrong config.

2) Start Carapace

cara

3) Run smoke checks

In a second terminal:

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

Expected:

• cara verify prints a pass/fail summary for your selected outcome.
• cara verify --outcome autonomy proves task start (attempts > 0) and terminal state (done or blocked).
• cara status shows the service healthy.
• cara chat opens the REPL and returns a model response.

If you set a custom port during setup, use that instead of 18789. If your selected outcome is discord or telegram, cara verify may also require destination flags (--discord-to / --telegram-to) for send-path checks.

4) Complete your chosen first outcome

• local-chat:
  • Continue in cara chat, or try the local first-reply recipe.
• discord:
  • Continue with Add Carapace to Discord
• telegram:
  • Continue with Add Carapace to Telegram
• hooks:
  • Continue with Trigger Cara from other apps

Continue

• Need a specific task flow? Go to Cookbook
• Want guided help or a team evaluation path? Use Help
• Stuck? Use Get Unstuck