Model provider keys and local models
Agents on a Harmony computer hold no model login. They reach their models through Harmony, on your own provider key first. Separately, models running on a computer you paired can answer in your own chats with Harmony, at no cost.
Add a provider key
- Open Profile → External agents and scroll to Model provider keys.
- On the provider's row, choose Add key. Each row says which agents use it, for example Not connected. Used by Codex and OpenCode on Harmony computers.
- Paste the key into the API key field and choose Save key.
The row then shows Connected, when you added it and when it was last used. Providers are Anthropic, OpenAI, Google Gemini, xAI, Mistral and OpenRouter. A provider marked Coming soon can't be used by agents yet.
| What you see | What it means |
|---|---|
| Connected | Agents on your Harmony computers use this key. |
| Not connected | You haven't added a key for this provider. |
| Rejected | The provider refused the key. Agents that would use it stop until you choose Replace; Harmony doesn't switch them to its own models. |
To change a key, choose Replace. To stop using it, choose Remove.
Use a key for chat and Loops too
A key's Use for chat and Loops switch decides who uses it:
- Off: only your coding agents use this key.
- On: Harmony also uses it for your chats and your Loops when you pick that provider's models, billed by the provider instead of counting against your usage limit.
For how models are chosen across Harmony, see Spend and models.
Which credential an agent uses
On a Harmony computer, for the person who asked:
- Your own key for a provider the agent can use.
- Your organization's key for that provider, when an admin added one in Models.
- Harmony's models, counted against your usage limit. Only agents that use Anthropic's models (Claude Code, and OpenCode) can fall back to them.
Each computer and agent says which one applies:
| Line | What it means |
|---|---|
| Uses your Anthropic key (or OpenAI, and so on) | Your key serves this agent. |
| Uses Harmony credits | No key of yours; the agent runs on Harmony's models, on your usage limit. |
| Your Anthropic key was rejected | Replace the key under Model provider keys. |
| Needs your OpenAI key | This agent has no fallback. Add the key, then save the agent. |
Agents on your own computer don't use any of this: they run on the login or key already on that computer, and Harmony never sees their model calls.
Local models
Models running on a computer you've paired can answer your own chats with Harmony.
- Start a model server on that computer. Harmony looks for Ollama (port 11434), LM Studio (1234), Jan (1337), llama.cpp (8080) and Msty. For a server on another port, choose Add server.
- Open Profile → External agents and find Local models. Each computer shows Models listed and when; choose Refresh to ask it again.
- On a model, choose Use. Harmony first checks it with seven test calls on your computer, which usually takes a few minutes. The model shows Waiting to check, then Checking, then what it's ready for, such as Ready for chat.
Harmony lists what each server has installed. To add a model, pull it with the server itself, for example ollama pull.
| What you see | What to do |
|---|---|
| Check failed or Check interrupted | Choose Retry check. |
| Did not answer within 20 seconds | Check the computer is awake and its runner is running, then refresh. |
| Offline | Wake the computer and log in. The runner starts again by itself. |
Choose Check again to re-run a check, or Stop using to remove a model.
Local models answer only in your own chats, never in shared rooms, background agents or Loops, and only while the computer is on. They cost nothing and never count against your usage limits. For self-hosted model servers your organization runs, see Local models.
FAQs
Is my key safe? Harmony stores it encrypted and never shows it again after you save it. Only agents on Harmony computers use it, unless you turn on Use for chat and Loops.
Why does Codex say it needs my OpenAI key? Harmony's own models are only for agents that use Anthropic's models. Add an OpenAI key, or run Codex on your own computer with its own login.
Why can't I pick my local model in a room? Local models only answer in your own chats, because they run on your computer.