# Credentials Source: https://docs.ideharmony.com/security/credentials The short version: **Harmony Core** does not store your provider CLI logins or model API keys. Auth happens where the agent runs. Optional **Harmony Pro** can store *other* secrets you add yourself — that is not a second copy of Claude or Codex keys. ## What Harmony Core does not have | Credential | Held by | |---|---| | Provider logins | The provider's own CLI, on the machine where you signed in | | Provider API keys | Your environment or the provider's store | | Model access tokens | The 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 Pro, [Account → Secrets](https://ideharmony.com/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 Pro, 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](/docs/cloud/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 | Secret | Where | |---|---| | Its own auth token for local RPC | The per-user data directory, namespaced by data suffix | | Optional Cloud device token | After 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](/docs/concepts/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. ## Related - [Security overview](/docs/security) - [Account and authentication](/docs/providers/account-and-authentication) - [Privacy](/docs/security/privacy) - [Cloud data handling](/docs/cloud/data-handling)