Account and authentication
Detected, installed, authenticated, and entitled are four different states. This page keeps them apart.
Most provider problems are really state-confusion problems. This page defines the states precisely so a failure can be placed correctly.
The state model
| State | Owner | Can Harmony observe it? |
|---|---|---|
| Detected | Harmony | Yes — it probes for the executable |
| Installed | Your machine | Yes, indirectly, via detection |
| Authenticated | The provider | Usually no |
| Entitled | The provider's billing | No |
| Available now | The provider's service | No, until a turn is attempted |
Harmony is authoritative for the first two and deliberately not authoritative for the rest. It does not hold your provider credentials, so it cannot report your login state or your plan.
IMPORTANT
A green launch button means "I can start this program." It does not mean "this will produce a model turn."
Where credentials live
Harmony does not collect, proxy, or store your provider credentials for first-party provider CLIs. Each provider authenticates the way it always does — its own login command, its own token store, or an API key in your environment.
For user-managed external harnesses (for example an ACP harness you run yourself), Harmony applies credential isolation so that harness's credentials are not shared with other providers in the workspace.
SECURITY
Treat provider output as untrusted input. A provider can be perfectly authenticated and still return content that tries to influence other tools. Permission prompts and approvals exist for that reason — see permissions and approvals.
Subscription-backed use versus API keys
Two different ways to pay, with different consequences:
| Subscription-backed CLI | API key | |
|---|---|---|
| You authenticate by | Signing in to the vendor's CLI | Supplying a key |
| Quota is governed by | Your plan | Your key's billing account |
| Harmony sees the balance | No | No |
| Typical failure | Plan limit reached | Key invalid, or spend cap hit |
Harmony supports both because it launches the provider's own CLI. Which one you get depends entirely on how you configured that CLI.
Diagnosing a provider
nala doctor
Reports what Harmony resolved: whether the executable was found, which path it resolved to, and the detected version. That is the boundary of what Harmony knows.
For anything past that boundary, ask the provider directly:
claude --version
If the provider works standalone but not under Harmony, the difference is
environment — a PATH or environment variable present in your shell but not in
the launched process. Compare the two.
Known limitations
- Harmony cannot report your remaining quota, plan tier, or rate-limit state for any provider. Those values are not exposed to it, and it does not guess them.
- Detection is a point-in-time probe. Installing a provider while Harmony is running may require a restart before it appears.
- A provider present in the registry is not a promise that it is installed, supported on your platform, or currently working.