Connect a provider
Bring your own agent CLI. What Harmony detects, what it cannot detect, and how to get from installed to a working turn.
Harmony does not sell model access and does not proxy your prompts through a service. It launches agent CLIs you already have, in panes it manages, and gives them shared tasks, artifacts, and messaging.
Outcome: one provider launching from Harmony and completing a turn.
The three states that get confused
This is the single most common source of "it does not work":
| State | Means | How Harmony knows |
|---|---|---|
| Installed | The provider's binary exists and resolves on PATH | Detected by probing |
| Authenticated | You have signed in to that provider | Harmony generally cannot see this |
| Entitled | Your plan permits the model you asked for | Harmony cannot see this |
IMPORTANT
Harmony can report a provider as detected and still be unable to run a turn. Detection is about the executable. Authentication and plan entitlements belong to the provider, and Harmony does not hold your provider credentials.
If a launch fails, check in that order: installed, then authenticated, then entitled.
Recognised providers
Harmony ships a registry of providers it knows how to launch, including Claude Code, Codex CLI, Devin CLI, Cursor, Grok, Kimi, Gemini, Qwen, Pi, Copilot, OpenCode, and the Harmony agent itself. The full generated list is at provider registry.
You can also define your own provider if you run an agent CLI that is not in the registry.
1. Install the provider CLI
Install the agent you want using that vendor's own instructions. Harmony does not install providers for you, and it does not bundle their credentials.
Verify the CLI works on its own, outside Harmony, before involving Harmony:
claude --version
If that fails, fix it there first. A provider that does not run in your own terminal will not run inside Harmony either.
2. Authenticate
Sign in using the provider's own flow. Most agent CLIs have a login command or read an API key from an environment variable.
SECURITY
Prefer the provider's own credential store over putting API keys in shell profiles that every process on your machine can read. Harmony isolates user-managed harness credentials where it manages them, but a key exported globally in your shell is visible to everything you run.
3. Launch from Harmony
Open the bottom orchestration bar in the desktop and click the provider, or launch it from the TUI:
/provider
Expected result: a pane opens, the provider's own startup output appears, and it reaches its ready prompt.
4. Verify a real turn
Ask for something trivial but real, in a repository:
List the files in this directory and tell me what this project does.
Expected result: the provider answers using your repository's contents. That confirms the whole chain: launch, authentication, working directory, and tool access.
Common recovery
| Symptom | Likely cause | Fix |
|---|---|---|
| Provider not offered in the bar | Binary not on PATH | Install it, restart Harmony, run nala doctor |
| Pane opens then exits immediately | Not authenticated | Run the provider's own login, outside Harmony |
| Turn starts, then errors about the model | Plan does not include that model | Choose a model your plan covers |
| Provider works in your terminal, not in Harmony | Environment differs | Run nala doctor and compare resolved paths |
The diagnostic that answers most of these:
nala doctor
Billing
Everything you spend goes to the provider whose plan you used, under that provider's pricing. Harmony itself is free to use and does not mark up inference.
NOTE
Harmony never spends your provider's quota without you launching a turn. There is
no background usage. If you see unexpected provider spend, look at the
sessions you started — nala tasks list and the transcript are the record.
Next
- Provider registry — every recognised provider id.
- Account and authentication — the state model in depth.
- First agent session