Skip to main content
Harmony
Download
View as Markdown (opens in a new tab)

Credentials

PreviewAvailable on: WindowsmacOSLinuxShips in the preview channel only. Not a stable release.

Where secrets live, what Harmony never holds, and the exposure you own yourself.

The short version: Harmony Core does not store your provider CLI logins or model API keys. Auth happens where the agent runs. Optional Harmony Cloud can store other secrets you add yourself — that is not a second copy of Claude or Codex keys.

What Harmony Core does not have

CredentialHeld by
Provider loginsThe provider's own CLI, on the machine where you signed in
Provider API keysYour environment or the provider's store
Model access tokensThe provider

Because Core does not hold those, it cannot leak them from its own store — 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.

Optional Cloud secret storage (not Core, not BYOK)

If you use Harmony Cloud, Account → Secrets is an optional, user-configured store for values a workspace needs in order to clone — typically HARMONY_REPO_URL and, for private repos, a read-only deploy key as HARMONY_GIT_SSH_KEY. It is not on the path of local Core.

What the server actually does (cloud-secret-server / cloud-secret-crypto):

  • Values are envelope-encrypted at rest (AES-256-GCM) with an operator master key (NALA_SECRETS_MASTER_KEY). That is not customer-held BYOK: you do not bring the wrapping key.
  • Plaintext is not returned after save. Decrypt happens in one place: writing ~/.harmony/secrets.env (mode 0600) inside your workspace VM.
  • Names that look like provider/model API keys are refused. Signing the agent in inside the workspace is how Claude Code / Codex CLI authenticate; those CLI credentials stay on that machine.
  • If the operator key is unset, the API answers secrets_unconfigured and stores nothing in the clear.

This is not a general-purpose vault, not a Harmony-routed model gateway, and not a claim that every secret in a git tree is blocked on upload. Known sensitive path patterns are refused on send-to-cloud; review the transfer list.

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:

  1. The provider's own credential store or login flow.
  2. A variable scoped to your user account rather than exported in a shell profile.
  3. A key in a shell profile — only when nothing else works.

Cloud transfers are not a complete secret scanner

When you send a repository to Harmony Cloud, known sensitive path patterns (.env, .ssh, key material, cloud config) are refused and cannot be overridden. That is not a guarantee that every secret in the tree is blocked. Files you confirm on the transfer list leave the machine. See data handling.

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

SecretWhere
Its own auth token for local RPCThe per-user data directory, namespaced by data suffix
Optional Cloud device tokenAfter you sign in for Cloud; revocable under Account → Devices

That local token authenticates local clients to the local daemon. It is not a credential for any model provider.

Credentials in diagnostics

Diagnostics do not deliberately collect secrets, but the surrounding material is sensitive.

WARNING

Before sharing harmony 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

  1. Revoke it at the provider. Do not start by deleting local files.
  2. Issue a replacement.
  3. 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.