Skip to Content
kosemdocs
Concepts

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. latest names the newest enabled version, so software that reads latest gets 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

ToYou need, on the secret, its project or its organization
See secrets and their versions, not their valuesAny basic role, or Secret Manager Viewer
Create secrets, add versions, disable and enable themOwner, Editor or Secret Manager Admin
Read a valueOwner, Secret Manager Admin or Secret Accessor
Destroy a version or delete a secretOwner or Secret Manager Admin
Share an organization's secret with projectsOwner or Secret Manager Admin, on the organization
Grant a secret to an agentsecrets.versions.access on the secret, and Agent Writer on the agent or Owner, Editor, Agents User or Agents Admin
Revoke a secret from an agentOwner on the agent, Owner or Agents Admin on its project, or Secret Manager Admin (IAM admin) on the secret

On this page