Carapace

Docs Hubs / Providers Hub

Providers Hub

Outcome

Pick a first provider with the shortest path to a verified useful outcome.

If you are undecided, do not optimize for the perfect long-term setup yet. Optimize for the shortest verified first run, then change providers later if needed.

Start with one provider only

Run cara setup --provider <provider> when you already know which provider you want, or plain cara setup if you want the wizard to ask. If you are unsure, choose local-chat as the first outcome and add channels only after cara verify --outcome auto passes.

The wizard always asks for the model — Carapace never picks one for you. Interactive mode prompts (e.g. Anthropic default model:); non-interactive mode requires --model <provider:model>, e.g. cara setup --provider anthropic --model anthropic:claude-sonnet-4-6. You can also pass --model interactively to skip the prompt. The <model-id> suffix is the provider-native model name from that provider's docs, console, or local endpoint; examples in this page show route shape and may age as providers rename or retire models.

In headless or scripted environments, pass --provider and --model; non-interactive cara setup errors instead of writing a providerless or modelless config.

Anthropic / OpenAI API key (fastest cloud path)

Pick one of these, not both:

export ANTHROPIC_API_KEY='...'
cara setup --provider anthropic

Or:

export OPENAI_API_KEY='...'
cara setup --provider openai

Anthropic also supports a setup-token-backed auth profile:

export CARAPACE_CONFIG_PASSWORD='...'
export ANTHROPIC_SETUP_TOKEN='...'
cara setup --provider anthropic --auth-mode setup-token

Notes:

Anthropic model snapshots vs. aliases

Anthropic publishes both stable-snapshot model IDs (date-suffixed, e.g. claude-haiku-4-5-20251001) and rolling aliases (no date suffix, e.g. claude-sonnet-4-6, claude-opus-4-7). Aliases track the latest snapshot for that family — production deployments that need exact-output reproducibility should pin a dated snapshot rather than the alias. This applies to the direct Anthropic API only; Bedrock and Vertex addressable IDs follow the conventions documented in their sections below (Bedrock: anthropic.<model-id>; Vertex: publishers/anthropic/models/<model-id> or <model-id>@<date> for older snapshots).

Codex (OpenAI subscription login)

export CARAPACE_CONFIG_PASSWORD='...'
export OPENAI_OAUTH_CLIENT_ID='...'
export OPENAI_OAUTH_CLIENT_SECRET='...'
cara setup --provider codex

Notes:

Ollama (fastest fully local path)

export OLLAMA_BASE_URL='http://127.0.0.1:11434'
cara setup --provider ollama

If your Ollama endpoint requires auth, the wizard will also offer an optional API key prompt and can write providers.ollama.apiKey from either direct input or ${OLLAMA_API_KEY}.

Claude CLI (local subscription-backed CLI path)

Claude CLI is configured directly rather than through the setup wizard. Run claude auth login to sign in with the local claude CLI first, then enable the backend and route a model to claude-cli:.

{
  "claudeCli": {
    "enabled": true
  },
  "agents": {
    "defaults": {
      "model": "claude-cli:default"
    }
  }
}

Vertex AI

Vertex AI supports Google Gemini models and third-party models from Anthropic, Meta, Mistral, and Nvidia. Authentication uses gcloud CLI credentials or the Google metadata server.

For local development, authenticate gcloud so gcloud auth print-access-token succeeds. On Cloud Run services, Cloud Run Jobs, and Cloud Run Worker Pools, Carapace bypasses gcloud and uses the metadata server directly.

export VERTEX_PROJECT_ID='my-gcp-project'
export VERTEX_LOCATION='us-central1'   # optional, defaults to us-central1
cara setup --provider vertex

vertex.gcloudTokenTimeoutMs controls how long Carapace waits for gcloud auth print-access-token before falling back to metadata. The default is 10 seconds; accepted values are 500-60000 milliseconds. Set CARAPACE_GCLOUD_TOKEN_TIMEOUT_MS only when overriding that default. The timeout is ignored on the Cloud Run/serverless bypass path because gcloud is not invoked there.

vertex.globalModels controls which Vertex models use the locations/global endpoint instead of vertex.location. The default is ["gemini-3*"], preserving Gemini 3 global routing. Set VERTEX_GLOBAL_MODELS to a comma-separated list to override the config value. Rules may use Gemini shorthand (gemini-3*, google/gemini-3.0-flash) or publisher paths (publishers/<publisher>/models/<model-id>); a trailing * matches a model ID prefix. This only changes routing location and does not validate model availability or IAM access. Set vertex.globalModels to [] to disable the default global routing rules.

Gemini models use the short form in agent config:

// agents.defaults.model or agents.list[].model
{ "model": "vertex:gemini-3.0-flash" }

Third-party models use the full publisher path from the Vertex AI Model Garden. You must enable the model's API in your GCP project first.

// agents.defaults.model or agents.list[].model
vertex:publishers/anthropic/models/claude-sonnet-4-6
vertex:publishers/meta/models/llama-3.1-405b-instruct-maas
vertex:publishers/mistral/models/mistral-large-2411
vertex:publishers/nvidia/models/llama-3.1-nemotron-70b-instruct

For third-party publishers, use the explicit publishers/<publisher>/models/<model-id> path. Check the Vertex AI Model Garden for the currently published model IDs per publisher.

Gemini / Bedrock / NEAR AI Cloud / Venice

These providers are supported directly by the setup wizard now. If multiple provider env vars are already set, prefer the explicit provider flag so setup does not rely on the interactive default.

export GOOGLE_API_KEY='...'
cara setup --provider gemini --auth-mode api-key

Gemini also supports Google sign-in:

export GOOGLE_OAUTH_CLIENT_ID='...'
export GOOGLE_OAUTH_CLIENT_SECRET='...'
cara setup --provider gemini --auth-mode oauth

Notes:

export AWS_REGION='us-east-1'
export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
cara setup --provider bedrock
export NEARAI_API_KEY='...'
cara setup --provider nearai

The default NEAR AI Cloud endpoint is https://cloud-api.near.ai/v1. Use nearai:<model-id> routing for NEAR AI Cloud, for example nearai:google/gemma-4-31B-it.

export VENICE_API_KEY='...'
cara setup --provider venice

If GOOGLE_API_KEY is only for other Google APIs and not for Gemini, unset it before running cara setup. If you need to override the default Gemini, NEAR AI Cloud, or Venice endpoint, the wizard will offer an optional base URL override.

Supported env vars:

Provider Routing

Carapace automatically routes your requests to the correct AI provider based on the model string configured in your agent (see agent.model).

Here is an example carapace.json5 snippet locking agents onto specific providers using prefixes:

{
  "agents": {
    "list": [
      {
        "id": "researcher",
        "model": "vertex:gemini-3.5-flash",
        "system": "You are a specialized research assistant."
      },
      {
        "id": "local-coder",
        "model": "ollama:qwen3-coder:30b",
        "system": "You are a local coding assistant."
      }
    ]
  }
}

Common first-run mistakes

When in doubt:

  1. choose one provider
  2. choose local-chat
  3. run cara setup --provider <provider>
  4. start cara
  5. run cara verify --outcome auto --port 18789

Capability matrix

Use the full support matrix for channels/providers/platforms:

Need help choosing?

Next paths