Skip to main content
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.
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.

​
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.
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.

​
Used in: Where It Applies

The Used in settings determine where the secret is selected for a session: 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.
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.

​
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: 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. 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

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.