# Providers Hub

## Outcome

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

## Recommended first choices

- **Fastest cloud start**: Anthropic or OpenAI
  - One API key, common setup path, best fit if your immediate goal is "get to first reply quickly."
- **Subscription-login path**: Codex
  - Best fit if you want OpenAI subscription-backed usage separated cleanly from API-key OpenAI.
- **Fastest local-only start**: Ollama
  - Best fit if your immediate goal is "keep everything local and verify the basic loop first."
- **Existing cloud standardization**: Gemini, Vertex AI, or Bedrock
  - Good if your environment is already centered on Google/Google Cloud or AWS.
- **NEAR AI Cloud path**: NEAR AI Cloud
  - Good if you want OpenAI-compatible routing through NEAR AI Cloud models.
  - Carapace connects to NEAR AI Cloud's HTTPS API; TEE attestation guarantees are provided by NEAR AI Cloud and are not independently verified by Carapace.
- **OpenAI-compatible alternative path**: Venice
  - Good if you specifically want Venice's endpoint and API shape.

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:

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

Or:

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

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

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

Notes:

- This keeps the Anthropic setup-token out of config and stores it in the encrypted auth-profile store.
- The resulting config uses `anthropic.authProfile`.
- `cara setup --provider anthropic --auth-mode api-key` keeps the existing direct API-key path.

#### 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)

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

Notes:

- Codex is separate from API-key `openai`.
- Codex sign-in is interactive-only in the CLI because it completes through a loopback callback on a local port.
- Control UI also supports Codex sign-in.
- The resulting config uses `codex.authProfile` and the model chosen during setup, such as `codex:default` or `codex:gpt-5.5`.
- `CARAPACE_CONFIG_PASSWORD` is required so the stored auth profile is encrypted at rest.

### Ollama (fastest fully local path)

```bash
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:`.

```json5
{
  "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.

```bash
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:

```json5
// 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.

```text
// 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](https://console.cloud.google.com/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.

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

Gemini also supports Google sign-in:

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

Notes:

- Gemini OAuth is interactive-only in the CLI because it completes through a loopback callback on a local port.
- Control UI also supports Gemini onboarding with either Google sign-in or API key.
- Gemini onboarding stores the Google OAuth client secret with the auth profile; it is not written into `config.json5`.
- Gemini Google sign-in requires `CARAPACE_CONFIG_PASSWORD` so the stored auth profile is encrypted at rest.

```bash
export AWS_REGION='us-east-1'
export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
cara setup --provider bedrock
```

```bash
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`.

```bash
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:

- `VERTEX_PROJECT_ID`, `VERTEX_LOCATION`, `VERTEX_MODEL`, `VERTEX_GLOBAL_MODELS` (Vertex AI)
- `CARAPACE_GCLOUD_TOKEN_TIMEOUT_MS` (optional Vertex AI `gcloud` token timeout)
- `ANTHROPIC_API_KEY`
- `OPENAI_API_KEY`
- `OPENAI_OAUTH_CLIENT_ID` / `OPENAI_OAUTH_CLIENT_SECRET` (Codex OpenAI sign-in)
- `GOOGLE_API_KEY`
- `GOOGLE_API_BASE_URL` (Gemini override)
- `GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET` (Gemini Google sign-in)
- `OLLAMA_API_KEY` (optional Ollama auth)
- `OLLAMA_BASE_URL` (if non-default)
- `AWS_REGION` or `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (Bedrock)
- `AWS_SESSION_TOKEN` (optional Bedrock session token)
- `NEARAI_API_KEY`
- `NEARAI_BASE_URL` (NEAR AI Cloud override)
- `VENICE_API_KEY`
- `VENICE_BASE_URL` (Venice override)

## Provider Routing

Carapace automatically routes your requests to the correct AI provider based on the `model` string configured in your agent (see [agent.model](../protocol/config-reference.md)).

- **Canonical Provider Prefix**: Every model requires an explicit `provider:model` colon prefix: `anthropic:claude-sonnet-4-6`, `openai:gpt-5.5`, `gemini:gemini-3.5-flash`, `vertex:gemini-3.5-flash`, `vertex:publishers/anthropic/models/claude-sonnet-4-6`, `bedrock:anthropic.claude-sonnet-4-6`, `ollama:qwen3-coder:30b`, `codex:default`, `nearai:google/gemma-4-31B-it`, `venice:llama-3.3-70b`, `claude-cli:opus`. Treat these as route-shape examples; provider docs, consoles, or local endpoints are authoritative for current model IDs.
- **No implicit routing**: Bare model names and slash-form values such as `openai/gpt-5.5` are rejected with a clear error. Always specify the provider with a colon.

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

```json5
{
  "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

- Multiple provider env vars are set, but you are not sure which one the setup path should use.
- The API key is exported in a different shell than the one running `cara setup` or `cara`.
- You start with a remote channel before local chat and provider verification work.
- You try to solve network exposure, channels, and provider choice all at once.

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:

- [Capability matrix](capability-matrix.md)

## Need help choosing?

- [Guided setup help](help.md#guided-setup-help)
- [Team setup / pilot request](help.md#team-setup-and-pilot-request)

## Next paths

- [Getting Started](../getting-started.md)
- [First Run](first-run.md)
- [Help](help.md)
- [CLI tasks index](cli-tasks.md)
- [Reference hub](reference.md)
