ReleaseLatest release v0.10.2 · 24 Eki 2026These pages describe v0.10.2, the published release.Changelog →

Connect a provider

Codewhale needs a model to answer. Save a key for a hosted provider, or point Codewhale at a model running on your own machine. You pay the provider directly; no Codewhale account is involved.

Save a provider key

Get an API key from your provider, then save it. Codewhale asks for the key and does not echo it. DeepSeek is the default provider, so it is the example here.

Terminal

codewhale auth set --provider deepseek
codewhale auth status --provider deepseek

auth status names the source in use — config file, secret store, or environment variable — and shows only the last four characters. In a script, pipe the key in with --api-key-stdin instead of typing it.

You can also connect from inside Codewhale: press F3 (or type /provider), choose a provider, paste the key, then pick a model.

Know which key is used

When a key is set in more than one place, the first match in this order wins:

  1. --api-key on the command line, for one run.
  2. api_key in ~/.codewhale/config.toml.
  3. The secret store written by codewhale auth set.
  4. The provider's environment variable, such as DEEPSEEK_API_KEY.

Exporting a new environment variable therefore does not replace a key you saved earlier. If a rotated key keeps failing, run auth status to see which source is active, then save the new key or clear the stored one:

Terminal

codewhale auth clear --provider deepseek

Note: A reported credential source is not proof that a key is accepted by the provider. doctor --json is an offline structural report; doctor --probe-api explicitly contacts the selected service and may incur provider usage.

On Linux the secret store is a private file (mode 0600) under ~/.codewhale/secrets/, not an OS keyring. codewhale doctor --probe-api makes one test call to confirm that the key and the network both work.

Use another provider or a local model

codewhale auth list shows the credential state Codewhale reports for each provider. For an API-key route, use codewhale auth set --provider <name> or its documented environment variable; OAuth and local routes have their own setup.

Save a key for another hosted provider, then select it and a model:

Terminal

codewhale auth set --provider anthropic
codewhale --provider anthropic --model claude-sonnet-5-5

A server you run yourself (vLLM, SGLang, Ollama) needs no API key by default. Connect a loopback endpoint, then select the model tag it serves:

Terminal

codewhale --provider vllm --model <model-tag>

The models page lists providers, local setups, and how to switch models mid-session.

Codewhale accounts

A provider key and a Codewhale account are different things. Local use never needs an account; anyone can sign in, and cloud computers are invite-only. Provider keys stay on your machine with codewhale auth set.

codewhale login
Sign in through your browser with a one-time code.
codewhale account status
Show which account this profile is signed in to.
codewhale account logout
Remove this profile's session.

codewhale login does not accept provider keys; those always go through codewhale auth set. The session is kept in your operating system's credential manager when one is available, and in the private Codewhale secrets file otherwise — for example over SSH or in a container. Sign in to Codewhale covers each surface step by step.

Next

Start your first task

Open Codewhale in a project and give it something concrete to do.

Set modes and approvals

Decide whether Codewhale asks before it runs commands.

See what leaves your machine

What the provider receives, what stays local, and how to turn usage counting off.