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:
--api-keyon the command line, for one run.api_keyin~/.codewhale/config.toml.- The secret store written by
codewhale auth set. - 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.