Configure an LLM provider

Task

Point Ethos at one of the four supported LLM providers — Anthropic, OpenAI, OpenRouter, or Ollama — and verify the next chat turn routes through it.

Result

ethos chat reaches the chosen provider, streams tokens back, and ethos doctor reports the provider as valid.

Prereqs

• ethos on PATH (Node 24+). Run ethos --version to confirm.
• An API key for the provider you're configuring, or a local Ollama install if you go that route.
• Write access to ~/.ethos/config.yaml.

Steps

The wizard handles the common path. Drop into hand-edit only when you need a non-default base URL or you're scripting the install.

Option A — Use the wizard

ethos setup

The wizard writes ~/.ethos/config.yaml and prompts for:

• Provider — one of anthropic, openai, openrouter, ollama.
• Model — the model id for that provider (see the table below).
• API key — stored locally in ~/.ethos/config.yaml. Skip for ollama.
• Default personality — pick one of the built-ins.

To re-run only the provider step on an existing config:

ethos setup auth
ethos setup model

Option B — Hand-edit the config

Open ~/.ethos/config.yaml and set four keys. The shape is plain key: value — no nested YAML.

provider: anthropic
model: claude-opus-4-7
apiKey: sk-ant-XXXXXXXXXXXX
personality: researcher

For OpenAI-compatible providers (openai, openrouter, ollama), add baseUrl if you want a non-default endpoint:

provider: openrouter
model: anthropic/claude-3.5-sonnet
apiKey: sk-or-XXXXXXXXXXXX
baseUrl: https://openrouter.ai/api/v1
personality: researcher

Provider matrix

provider	Default base URL	Where to get a key	Notes
anthropic	n/a (SDK default)	console.anthropic.com	Best fit for claude-* models; supports key rotation via ethos keys.
openai	https://api.openai.com/v1	platform.openai.com	Use for gpt-4o, o1, etc.
openrouter	https://openrouter.ai/api/v1	openrouter.ai/keys	One key for Claude, GPT, Gemini, Llama, and 200+ more.
ollama	http://localhost:11434/v1	n/a — local	Leave apiKey: set to any non-empty placeholder; the server ignores it.

Provider strings are validated against packages/wiring/src/provider-catalog.ts. Anything else is rejected by ethos doctor.

Ollama specifics

Pull and run the model before pointing Ethos at it:

ollama pull llama3.1:8b
ollama serve   # leave running

Then in ~/.ethos/config.yaml:

provider: ollama
model: llama3.1:8b
apiKey: ollama
baseUrl: http://localhost:11434/v1
personality: researcher

Optional — a fallback chain

Stack two providers so Ethos fails over automatically when the first one rate-limits or 5xx's. The chain triggers when two or more providers.<n>.* blocks are present.

provider: anthropic
model: claude-opus-4-7
apiKey: sk-ant-XXXXXXXXXXXX
personality: researcher

providers.0.provider: anthropic
providers.0.apiKey: sk-ant-XXXXXXXXXXXX
providers.0.model: claude-opus-4-7

providers.1.provider: openrouter
providers.1.apiKey: sk-or-XXXXXXXXXXXX
providers.1.model: anthropic/claude-3.5-sonnet

The top-level provider, model, and apiKey keys stay in place — they're used when the chain has fewer than two entries.

Verify

Run the health check and then one turn:

ethos doctor

doctor reports the active provider, the model, whether the SDK module is installed, and whether the API key is reachable.

Then:

ethos chat -q "respond with the single word 'ok'"

A streamed ok and a non-zero usage line means the provider, key, and model resolved end-to-end.

Troubleshoot

Unknown provider 'foo'. Did you mean 'anthropic'? — ethos doctor rejects provider strings outside the catalog. Set provider: to one of anthropic, openai, openrouter, ollama.

401 Unauthorized from the provider. — The key is wrong, expired, or missing the right scope. Regenerate at the provider console and re-run ethos setup auth.

ECONNREFUSED 127.0.0.1:11434 with provider: ollama. — ollama serve is not running. Start it in another terminal or check lsof -i :11434.

model not found from OpenRouter. — OpenRouter model ids are namespaced (anthropic/claude-3.5-sonnet, not claude-3.5-sonnet). Copy the exact id from the OpenRouter model page.

Empty stream, no error. — The base URL points at an endpoint that accepts requests but returns nothing useful (common with custom OpenAI-compatible gateways). Run ethos doctor and compare baseUrl against the provider's docs.

Rate-limited on Anthropic. — Add a rotation key with ethos keys add (Anthropic only) or fall back via the providers.<n> chain shown above.