Secrets
How dashsquad keeps, encrypts and gives API keys, tokens and other credentials to your agents.
dashsquad keeps different types of secrets: AI provider API keys and sign-ins, HQ access tokens, relay credentials, Telegram and WhatsApp credentials, and MCP connector settings. This page tells you where each secret is and how dashsquad protects it.
Where secrets live
| Secret | Location | Protection |
|---|---|---|
| HQ management and chat tokens, relay and remote-access credentials, your dashsquad sign-in (Desktop) | The OS keychain | macOS Keychain, Windows Credential Manager or libsecret on Linux |
| Provider API keys and sign-ins, the Brave Search key, Telegram and WhatsApp credentials | ~/.dash/gateway/credentials.enc | A file encrypted with AES-256-GCM |
| The identity key of the HQ for the relay | ~/.dash/gateway/relay-gateway-key | A file with 0600 permissions |
| MCP connector headers and environment values | ~/.dash/gateway/mcp/configs.json | A file with 0600 permissions. It is not encrypted. |
| WhatsApp session data | The WhatsApp session folder of the channel | Files on the disk |
| Tokens in the apps | The app on your device | iOS Keychain, Android Keystore encryption, or browser storage in the web app |
The paths in this table are for a standalone HQ, with the HQ folder ~/.dash/gateway. For an HQ that Desktop starts, the HQ folder is ~/.dashsquad/<hq id>. See Data folders.
HQ tokens
When Desktop starts the HQ for the first time, it makes a management token and a chat token. It keeps them in the OS keychain, not in a plain-text file. When Desktop starts again, it reads the tokens from the keychain and connects to the HQ again.
If your Mac has a dashsquad item in the keychain, the setup wizard first shows an example of the macOS keychain window. When macOS asks you to let dashsquad get access to these credentials, click Always Allow. Then your Mac does not ask again.
Desktop gives the tokens to the HQ in the DASHSQUAD_HQ_TOKEN and DASHSQUAD_HQ_CHAT_TOKEN environment variables when it starts the HQ.
The keychain also keeps the relay and remote-access credentials of Desktop and your dashsquad sign-in. Refer to Remote access.
Provider keys and channel tokens
The HQ keeps all other secrets in its encrypted credential store at ~/.dash/gateway/credentials.enc. These secrets include:
- Your AI provider keys, for example for Anthropic, OpenAI, Google, Moonshot (Kimi) and OpenRouter, and the keys for plugin providers.
- The tokens from a sign-in with a Claude account or an OpenAI account.
- The Brave Search API key for
web_search. - Telegram bot tokens and WhatsApp credentials.
You add these secrets in Desktop, or in the web app, the iOS app or the Android app. Do not edit the file yourself.
The HQ does not show a saved key again. A client can see only the key names, not the values.
The encrypted credential store
The HQ encrypts the credential store with a random key that it makes when it starts for the first time:
| Property | Value |
|---|---|
| Algorithm | AES-256-GCM (authenticated encryption) |
| Key | A 256-bit key from scrypt and a random password. The HQ keeps it in ~/.dash/gateway/secret.key. |
| Salt | 256-bit random value, one for each store |
| IV | 96-bit random value, a new one for each write |
| Authentication tag | 128-bit GCM tag (integrity check) |
| File permissions | 0600 (only the owner can read and write) on secret.key and on credentials.enc |
You do not need a password, and you do not need to unlock the store. The HQ reads its key from secret.key automatically when it starts. Both files are in ~/.dash/gateway/ with 0600 permissions. Protect that folder as you protect other local secrets.
Writes are atomic
Each write goes to a temporary file first, with a name such as credentials.enc.<random-id>.tmp. Then the HQ renames it to credentials.enc in one step. If the process stops during a write, the previous version stays correct.
How secrets reach your agents
When you add a provider key in Desktop, these steps occur:
You add a key
On the AI Providers page (or in the setup wizard), you paste a provider API key. Or you sign in with your Claude account or OpenAI account.
Desktop sends the key to the HQ
Desktop sends the key to the Management API of the HQ. The HQ writes it to the encrypted credential store. The HQ does not write the key to a plain-text file.
The HQ reads the key for each turn
For each turn of an agent, the HQ reads the current keys from the encrypted store. If you change or delete a key, the change applies to the next message of the agent. You do not need to restart.
The HQ does not put provider keys in environment variables or command arguments, where they can go into logs or process lists.
Accounts that you sign in with
For an account sign-in (Claude or OpenAI), the store keeps three values: the access token, the refresh token and the expiry time. Before each turn, the HQ gets a new access token if the current token expires in less than 30 minutes. If the provider refuses a token, the HQ also tries to get a new token.
HQ without Desktop
If you run the HQ without Desktop, add provider keys from a client app (the web app, the iOS app or the Android app). Or use the Management API: POST /credentials with a key and a value. Refer to API reference.
Set the management token and the chat token in the DASHSQUAD_HQ_TOKEN and DASHSQUAD_HQ_CHAT_TOKEN environment variables. Refer to Configuration.
Key names
The credential store uses these key names:
| Key name | Use |
|---|---|
<provider>-api-key:<name> | A provider API key or an access token, for example anthropic-api-key:default |
<provider>-oauth-refresh:<name>, <provider>-oauth-expires:<name> | The refresh token and the expiry time of an account that you signed in with |
brave-api-key:default | The Brave Search API key |
channel:<name>:token | The bot token of a Telegram channel |
channel:<name>:whatsapp-auth | The credentials of a WhatsApp channel |
You can keep more than one key for a provider. For each turn, the HQ uses one key for each provider:
- Usually, the HQ uses the first key in the store that is not empty.
- If the first key comes from an account sign-in, the HQ uses the signed-in account with the latest expiry time.
- If the refresh of an account failed, the HQ can use a different key for that provider.
If you save a new Telegram token, the HQ restarts that Telegram channel.
Security properties
This section tells you what the encrypted store protects against.
Protected:
- A person who reads the encrypted file from the disk without the key (AES-256-GCM).
- Changes to the encrypted file. The GCM authentication tag finds the changes.
- Data loss if the HQ stops during a write (atomic rename).
Not protected:
- A person who can read
secret.keyandcredentials.enc. The key decrypts the store, so keep~/.dash/gateway/private. - MCP connector headers and environment values in
mcp/configs.json. They are not encrypted. - Secrets in the memory of an HQ process that runs.
- A computer where an attacker has the permissions of your user account.
Run the HQ in an isolated environment if you need more security. Change your API keys regularly, because a leaked key stays valid until you change it.