Credentials
Where secrets live, what Harmony never holds, and the exposure you own yourself.
The short version: Harmony does not hold your provider credentials. That is a deliberate design choice, and it has consequences in both directions.
What Harmony does not have
| Credential | Held by |
|---|---|
| Provider logins | The provider's own CLI |
| Provider API keys | Your environment or the provider's store |
| Model access tokens | The provider |
Because Harmony does not hold them, it cannot leak them — and it also cannot tell you whether you are signed in, what plan you have, or how much quota remains. Those limits in the documentation are a direct consequence of this design, not an oversight.
The exposure you own
SECURITY
An API key exported globally in your shell is readable by every process you run, including every agent you launch. Agents execute commands in that environment. This is the single largest credential risk in normal Harmony use, and it is entirely under your control.
Prefer, in order:
- The provider's own credential store or login flow.
- A variable scoped to your user account rather than exported in a shell profile.
- A key in a shell profile — only when nothing else works.
Credential isolation for managed harnesses
For user-managed external harnesses — an ACP harness you run yourself — Harmony applies credential isolation so that harness's credentials are not shared with other providers in the workspace.
If such a harness fails to authenticate while first-party providers work, that boundary is usually why. It is intended behaviour, not a bug. Supply its credentials through its own configuration.
What Harmony does hold
| Secret | Where |
|---|---|
| Its own auth token for local RPC | The per-user data directory, namespaced by data suffix |
That token authenticates local clients to the local daemon. It is not a credential for any external service.
Credentials in diagnostics
Diagnostics do not deliberately collect secrets, but the surrounding material is sensitive.
WARNING
Before sharing nala doctor --json, a support bundle, a screenshot, or a
terminal capture: check for keys, tokens, absolute paths containing your
username, and repository names you would rather not disclose. A screen capture
includes whatever is on screen, including an environment variable you echoed
five minutes ago.
Credentials and agents
Treat an agent as a process running with your environment, because that is what it is.
- It can read files your user can read.
- It can run commands your user can run.
- It sees environment variables present in its launch environment.
Worktrees do not change this. They are file isolation so parallel agents do not collide — not a security boundary. See worktrees.
Remote messages
Messages arriving from peer machines over LAN Link render as text only. They are never pasted into a PTY and never routed to an execute path, so a peer cannot cause your machine to run a command — or exfiltrate a variable — by messaging you.
If a credential is exposed
- Revoke it at the provider. Do not start by deleting local files.
- Issue a replacement.
- Then clean up local copies, shell profiles, and history.
Revoke first: a key that still works is a live risk regardless of what you deleted locally.