Secrets
How kosem keeps encrypted, versioned values such as API keys, passwords and registry tokens, shares them with projects, and passes them to agent commands.
A secret is an encrypted, versioned value that an organization or a project keeps for its software and agents, such as an API key, password or private container registry token. Every read is recorded in the audit logs.
For short-lived GitHub, Google Cloud or AWS credentials backed by keyless trust rather than stored keys, use Connections and access profiles.
How it works
- A secret has a name, such as
stripe/secret_key, that people and software call it by: lowercase letters, digits and_, in parts separated by/, starting with a letter. Names are unique in their organization or project. - Its value is in versions, numbered from 1, each written once and up to 64 KiB.
latestnames the newest enabled version, so software that readslatestgets a new value as soon as you add it. - A version is enabled, disabled or destroyed. A disabled version can't be read until it's enabled again. Destroying a version deletes its value for good and keeps its number. Deleting a secret destroys all of its versions.
- A value is read only on purpose. Lists and pages show secrets and their versions, never their values. Reading a value is its own request, which the Data Access audit log records whatever your organization's settings say.
Organization secrets and project secrets
A project keeps the secrets that only it needs. An organization keeps those that several projects share, such as a monitoring service's key, and chooses which projects have them: all of them, including future ones, or the ones you select.
- A project has a shared secret at once, as a secret of its own that reads the organization's versions. The project can rename it and choose who reads it, but not add or change versions: those are the organization's.
- A project's own secret wins. If a project already has a secret by the same name, it keeps its own and doesn't get the shared one until its own is deleted or renamed.
- Unsharing removes it at once, with every agent's grant of it in that project.
Secrets for agents
An agent receives a secret only when someone who can read it explicitly grants it to the agent, either before starting, mid-conversation, or by approving an agent's request_access prompt.
When running shell commands, the agent passes granted secrets per command through exec's secrets parameter (as ENV_VAR=alias or file:filename=alias under /run/kosem/secrets). Values are injected into that single command alone, never kept in persistent shell state, and are redacted from live command output.
Each use is recorded in the System Events audit log. The agent has no IAM role on the secret: its access is the grant, which lasts until revoked (from the agent or from the secret's Agents tab), expired, or deleted.
Whatever runs in a command given a secret can read its value, and so can anyone who can write to the agent. kosem redacts secret values in command output, which stops no command from revealing them indirectly. Grant agents only what their work needs, and prefer short-lived access profiles whenever available.
Why it works this way
- Reading a value is a permission of its own. Only Owner among the basic roles has it, so an organization's Viewers and Editors can see and manage secrets without seeing their values.
- Versions, not edits. A value is never changed in place, so a new key rolls out by adding a version and disabling the old one once nothing uses it.
- Per-command injection. Passing static secrets only to the commands that ask for them avoids leaking long-lived keys to every process in an environment.
Who can do what
| To | You need, on the secret, its project or its organization |
|---|---|
| See secrets and their versions, not their values | Any basic role, or Secret Manager Viewer |
| Create secrets, add versions, disable and enable them | Owner, Editor or Secret Manager Admin |
| Read a value | Owner, Secret Manager Admin or Secret Accessor |
| Destroy a version or delete a secret | Owner or Secret Manager Admin |
| Share an organization's secret with projects | Owner or Secret Manager Admin, on the organization |
| Grant a secret to an agent | secrets.versions.access on the secret, and Agent Writer on the agent or Owner, Editor, Agents User or Agents Admin |
| Revoke a secret from an agent | Owner on the agent, Owner or Agents Admin on its project, or Secret Manager Admin (IAM admin) on the secret |