> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashsquad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> How Dash stores, encrypts, and delivers API keys and credentials to your agents.

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

| Secret                               | Stored in                         | Protection                                                       |
| ------------------------------------ | --------------------------------- | ---------------------------------------------------------------- |
| HQ management & chat tokens          | OS keychain                       | macOS Keychain / Windows Credential Manager / libsecret on Linux |
| Provider API keys & messaging tokens | `~/.dash/gateway/credentials.enc` | AES-256-GCM encrypted file                                       |

### 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:

| Property         | Value                                                                            |
| ---------------- | -------------------------------------------------------------------------------- |
| Algorithm        | AES-256-GCM (authenticated encryption)                                           |
| Key              | Random 256-bit key, derived via scrypt and saved to `~/.dash/gateway/secret.key` |
| Salt             | 256-bit random, unique per store                                                 |
| IV               | 96-bit random, unique per write                                                  |
| Auth tag         | 128-bit GCM tag (integrity check)                                                |
| File permissions | `0600` (owner read/write only) on both `secret.key` and `credentials.enc`        |

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:

<Steps>
  <Step title="You enter a key in Desktop">
    On the **AI Providers** page (or the setup wizard), you paste a provider API key.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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):

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
```

See [AI Providers](/ai-providers#configuring-credentials) for the full list of variables. Set the management and chat tokens with the `--token` and `--chat-token` flags (see [Configuration](/configuration#running-the-hq-standalone)).

## What's stored

Desktop uses well-known key names for credentials:

| Key pattern                 | Purpose                                             |
| --------------------------- | --------------------------------------------------- |
| `<provider>-api-key:<name>` | Provider API key (e.g. `anthropic-api-key:default`) |
| Messaging app credentials   | Telegram bot tokens, WhatsApp session data          |

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.