> ## 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>**Use Secrets for sensitive environment variables in cloud agents.** A secret is automatically exported only when the session is authorized to use it, its applicability covers the session's Space, and auto-install is enabled. 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 under **Settings → Capabilities → Secrets** in the Cosmos menu. 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.

## Access and Applicability

**Who can use a secret and where it applies are separate settings.** Sharing an MCP server or adding a resource to a Space does not replace the secret's own access settings.

### Sharing: Who Can Use It

For a shareable secret, open **Sharing → Manage access** in its editor, or choose **Share** from the secret's menu. Grant **Can use** to the intended people, groups, or service accounts. For organization-wide access, set **General access → Organization access** to **Can use** (shown as **Everyone → Can use** in some versions), then save. This grants use within your organization, not public access, and does not reveal the stored value in the UI.

Grant only the access needed. If the sharing control is unavailable, ask the secret owner to check your permissions. **Only me** secrets remain personal and cannot be shared directly; create a **Scoped access** or **Organization-wide** secret for shared use instead.

<Warning>Use access allows agents and automations to use the credential. People who can contribute to one of your shared sessions may also cause that session to use your personal secrets. Keep credentials out of prompts, repositories, and tool output.</Warning>

### Used in: Where It Applies

The **Used in** settings determine where the secret is selected for a session:

| Choice | Applicability |
| - | - |
| **Only me** | Personal to sessions you own, in **Every Space** or **Selected Spaces**. Every Space includes future Spaces; it does not grant other people access. |
| **Scoped access** | Applies in the selected target Spaces. Grant use access separately to the intended recipients. |
| **Organization-wide** | Applies in every current and future Space. Available to admins when creating a secret; use access must still be granted separately. |

The category is fixed at creation. You can later edit the selected Space coverage of personal or scoped secrets, but cannot turn a personal secret into an organization-wide one by changing its access grants.

When multiple eligible values target the same environment variable or file path, personal values take priority over selected-Space values, which take priority over organization-wide values. A personal value for selected Spaces takes priority over one for Every Space.

<Note>Older screens and guides may describe **Private/Shared visibility**. In the current UI, check **Sharing**, **Used in**, and installation independently; neither an organization-wide grant nor Every Space coverage alone guarantees a secret will reach a session.</Note>

## Creating a Secret

1. Go to **Settings → Capabilities → Secrets** from the Cosmos menu.
2. Choose **Add a secret** and the environment-variable option.
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.
   * **Applicability** — choose **Only me**, **Scoped access**, or **Organization-wide**, and select Space coverage where applicable. Review this later under **Used in**.
   * **Auto-install in environments** — leave on to inject the selected value into authorized new environments. Turn it off to store the secret without automatic injection.
4. Save the secret. For shared use, grant the intended recipients **Can use** through **Manage access** and confirm the grants saved.

The new secret appears in the list. Validate it in a fresh session owned by an intended recipient in the target Space.

## Auto-Injection into VMs

An authorized, applicable environment-variable secret with **Auto-install in environments** enabled is exported as a shell variable on VM boot. Installation does not grant access or change **Used in** coverage. 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 in the target Space and prompt: *"Check whether `$OPENAI_API_KEY` is set in this workspace. Report only whether it is present; do not print its value."*

For a generic secret referenced by an MCP server, also grant use access on the [MCP configuration](/cosmos/config-mcp#referenced-secrets-need-separate-access). Test a harmless read-only MCP call in a fresh session as the intended recipient; a successful test as the owner does not verify someone else's access.

## 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 | ✅ (**Only me**) | ❌ — 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. Validate the change in a fresh session.
* **Deletion and access changes** — deleting a secret or revoking access does not recall values already delivered to running sessions. If a credential has been exposed, revoke or rotate it at its source as well.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.