Skip to main content
Dash handles several kinds of secrets: AI provider API keys, HQ access tokens, and messaging app credentials. They are stored in two places, both protected at rest.

​
Where secrets live

​
HQ tokens

When Desktop spawns the HQ, it generates management and chat tokens and stores them in the OS keychain — never in plaintext files. When Desktop relaunches, it reads the tokens from the keychain to reconnect to the existing HQ.

​
Provider keys and messaging tokens

Everything else — your Anthropic/OpenAI/Google/Moonshot/OpenRouter keys, and Telegram/WhatsApp credentials — is encrypted in the HQ’s credential store at ~/.dash/gateway/credentials.enc. You set these through Desktop; you never edit the file by hand.

​
The encrypted credential store

The HQ encrypts the credential store with a random key it generates on first run: There is no password to remember and nothing to unlock — the HQ loads its key from secret.key automatically at startup. Both files sit in ~/.dash/gateway/ with 0600 permissions, so protect that directory the way you would any local secret.

​
Writes are atomic

Every write goes through a temporary file first: the encrypted payload is written to credentials.enc.tmp, then atomically renamed. If the process crashes mid-write, the previous version stays intact.

​
How secrets reach your agents

When you add a provider key in Desktop, here’s the handoff:
1

You enter a key in Desktop

On the AI Providers page (or the setup wizard), you paste a provider API key.
2

Desktop sends it to the HQ

The key is sent to the HQ’s Management API and written to the encrypted credential store. It is never written to a plaintext file.
3

The HQ reads it on each run

When an agent runs, the HQ reads the current keys straight from the encrypted store. Rotating or deleting a key takes effect on the agent’s next message — no restart needed.
This keeps secrets out of environment variables and command-line arguments, where they could leak into logs or process listings.

​
Standalone HQ

When you run the HQ without Desktop, supply provider keys as environment variables (for example in an .env file or your Docker environment):
See AI Providers for the full list of variables. Set the management and chat tokens with the --token and --chat-token flags (see Configuration).

​
What’s stored

Desktop uses well-known key names for credentials: The HQ collapses <provider>-api-key:* entries into one key per provider when an agent runs, so you can keep more than one key per provider and the first non-empty one is used.

​
Security properties

A summary of what the encrypted store protects against and what it doesn’t. Protected:
  • Reading secrets from disk without the key (AES-256-GCM)
  • Tampering with the encrypted file (the GCM authentication tag detects modifications)
  • Data loss from crashes during writes (atomic rename)
Not protected:
  • An attacker who can read both secret.key and credentials.enc (the key decrypts the store) — keep ~/.dash/gateway/ private
  • Memory-resident secrets in a running HQ process
  • A compromised machine with the user’s privileges
For higher-security deployments, run the HQ in an isolated environment and rotate API keys regularly.