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

# Managing Secrets

> Store API keys, tokens, and credentials in the Cosmos Secrets Manager and inject them into Expert VMs at boot.

Anything that would be a bad idea to type into a chat — API keys, OAuth tokens, certs, DB URLs — goes in the Secrets Manager. Cosmos exports them into the Expert VM at boot. They're encrypted on disk and stripped from logs.

<Note>**Secrets are how you set environment variables for cloud agents.** There is no separate env var feature for cloud-agent VMs — every secret in scope is automatically exported as a shell variable in the VM. Environment-scoped environment variables (set on the Environment itself) are for **non-sensitive defaults only** (e.g. `NODE_ENV=development`) and are shared with every user of that environment.</Note>

## Where to Find It

The Secrets Manager lives in the sidebar under **Configuration → Secrets**. You can add, edit, delete, and search secrets from there. Values are write-only — once saved, you cannot read them back. Rotating means editing and pasting the new value.

## Scopes

When you create a secret, choose its visibility:

| Scope       | Visibility                                   |
| ----------- | -------------------------------------------- |
| **Private** | Only your sessions can read it.              |
| **Shared**  | Visible to all members of your organization. |

If a secret with the same name exists in both Private and Shared scope, your sessions read the Private one.

## Creating a Secret

1. Go to **Configuration → Secrets** in the sidebar.
2. Click **+ Add Secret**.
3. Fill in:
   * **Name** — used as the variable name when injected (e.g. `OPENAI_API_KEY`).
   * **Value** — the secret value. Pasted in once and never shown again.
   * **Visibility** — **Private** or **Shared**.
   * **Automatically install in VMs** — leave on so the secret is auto-exported as an environment variable in every Expert VM in scope. Turn it off to keep the secret in storage but skip auto-injection.
4. Click **Create Secret**.

The new secret appears in the list and is available to sessions on their next VM boot.

## Auto-Injection into VMs

By default, every in-scope secret with **Automatically install in VMs** enabled is exported as a shell variable on VM boot. The exported variable name is the **upper-snake-case** of the secret name:

| Secret name       | Exported as        |
| ----------------- | ------------------ |
| `openai-api-key`  | `$OPENAI_API_KEY`  |
| `pagerduty.token` | `$PAGERDUTY_TOKEN` |
| `db_url`          | `$DB_URL`          |

To verify a secret is available, start a new session and prompt: *"Check whether `$OPENAI_API_KEY` is set in this workspace."*

## Secrets vs Environment Variables

| Concern                                | Secrets Manager | Environment variables on an Environment                         |
| -------------------------------------- | --------------- | --------------------------------------------------------------- |
| API keys, tokens, credentials          | ✅               | ❌ — values are committed into the environment's version history |
| Per-user values                        | ✅ (Private)     | ❌ — same value for everyone using the environment               |
| Public defaults (paths, feature flags) | Possible        | ✅                                                               |
| Auto-exported as `$FOO` in VM shell    | ✅               | ✅                                                               |

**Rule of thumb:** sensitive or per-user → Secrets Manager; public/shared defaults tied to an environment → environment variables on the Environment.

## Limits and Lifecycle

* **Versioning** — each secret has an opaque version; saving a new value rotates it.
* **Rotation** — there is no built-in scheduler. Rotate by editing the secret and entering the new value.
* **Deletion** — deleting a secret removes it from future VM boots; existing running sessions keep the value already exported.