user-secret

A user-secret holds one encrypted value scoped to a single developer. Unlike a tenant-wide secret, it is bound to the developer who created it and is delivered only to agents that developer spawns. User-secrets are created automatically by murmur setup when you onboard your credentials. You can also manage them with murmur secret set --user, murmur secret ls --user, and murmur secret rm --user, which take the leaf name (the part after {provider}/{username}/), or with murmur set using the full name.

Fields

Name	Type	Required	Description
`name`	string	yes	Full secret name: `{provider}/{username}/{LEAF}` (e.g. `github_oauth/alice/GH_TOKEN`). A new secret must sit under your own prefix, and its leaf must match `[A-Z][A-Z0-9_]*` and not start with `MURMUR_`.
`plaintext_value`	bytes	yes (on write)	Secret value, base64-encoded in YAML or JSON. Write-only: cleared after encryption and never returned by read or list operations.
`declared_kind`	string	no	What the credential is, for example `github.pat_fine_grained`. Enables a shape check and an identifying hint. Write-only.
`descriptor`	object	no (read-only)	What the credential is, as declared when it was stored, with any identifying hint. Set by the server.
`created_at`	timestamp	no	Timestamp of last update. Set automatically on each write.
`description`	string	no	Human-readable description.

The plaintext_value field is write-only. When you read a user-secret back with murmur get, the response contains name, createdAt, description, and descriptor, never the value.

Name convention

The built-in murmur-member-self tenant-binding grants each developer user-secret.read, user-secret.create, user-secret.edit, and user-secret.delete on matching {provider}/{username}/* names. read also supplies visibility in listings. The murmur setup command follows this convention automatically, producing names like:

Well-known secret	Stored name
GitHub token	`github_oauth/alice/GH_TOKEN`
Anthropic API key	`github_oauth/alice/ANTHROPIC_API_KEY`
Signing key	`github_oauth/alice/SIGNING_KEY`
Claude OAuth token	`github_oauth/alice/CLAUDE_TOKEN`
Claude refresh token	`github_oauth/alice/CLAUDE_REFRESH_TOKEN`
OpenAI API key	`github_oauth/alice/OPENAI_API_KEY`

A new user-secret must use this {provider}/{username}/{LEAF} form. The server rejects any other name on creation.

Examples

Setting a user-secret via murmur setup

murmur setup creates user-secrets automatically as part of onboarding:

murmur setup

This encrypts your GitHub token, signing key, and any configured API keys as user-secrets under your identity prefix.

Creating a user-secret manually

With the secret command, which takes the leaf name and stores stdin’s exact bytes:

printf 'sk-custom-key' | murmur secret set --user CUSTOM_KEY

Set your secret "CUSTOM_KEY". Deliver it with 'murmur secret mount CUSTOM_KEY'.

With the catalog API, which takes the full name and a base64 value:

echo '{"name":"github_oauth/alice/CUSTOM_KEY","plaintext_value":"c2stY3VzdG9tLWtleQ=="}' \
  | murmur set user-secret github_oauth/alice/CUSTOM_KEY

Listing your user-secrets

murmur get user-secret

github_oauth/alice/ANTHROPIC_API_KEY
github_oauth/alice/GH_TOKEN
github_oauth/alice/SIGNING_KEY

The list prints one name per line. murmur secret ls --user lists your own leaves in a NAME KIND HINT table.

Reading a single user-secret

murmur get user-secret github_oauth/alice/GH_TOKEN

The response includes name, createdAt, and description. The value is stripped.

Deleting a user-secret

murmur rm user-secret github_oauth/alice/CUSTOM_KEY

A user-secret that your user record references (e.g. through github_token_secret or secret_mounts) cannot be deleted. Remove the reference first, for example with murmur secret unmount.

How user-secrets reach agents

When you spawn an agent, the system reads your user record and resolves each referenced user-secret. The well-known credential fields map to environment variables on the agent VM:

User record field	User-secret name	Environment variable
`github_token_secret`	`github_oauth/alice/GH_TOKEN`	`GH_TOKEN`
`anthropic_api_key_secret`	`github_oauth/alice/ANTHROPIC_API_KEY`	`ANTHROPIC_API_KEY`
`openai_api_key_secret`	`github_oauth/alice/OPENAI_API_KEY`	`OPENAI_API_KEY`
`signing_key_secret`	`github_oauth/alice/SIGNING_KEY`	`SIGNING_KEY`

Claude and OpenAI OAuth credentials (claude_token_secret, claude_refresh_token_secret, and the openai_oauth_* fields) are subscription credentials Murmur refreshes and assigns itself. They are not exported under their stored names. Any other user-secret reaches your agents only when your user record’s secret_mounts lists it. Add one with murmur secret mount.

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`secret name is required`	Provide a non-empty `name` in the resource ref and payload.
`INVALID_ARGUMENT`	`secret name "X" must be "{provider}/{account}/" followed by a leaf`	Create the secret under your own prefix, for example `github_oauth/alice/CUSTOM_KEY`.
`INVALID_ARGUMENT`	`user secret leaf: secret name "X" must match [A-Z][A-Z0-9_]*`	Use an uppercase leaf of letters, digits, and underscores, starting with a letter.
`INVALID_ARGUMENT`	`plaintext_value is required`	The write payload must include a `plaintext_value`. Pipe the value via stdin or include it in the JSON body.
`INVALID_ARGUMENT`	`ref name "X" does not match payload name "Y"`	The name in the resource ref and the `name` field in the payload must match.
`FAILED_PRECONDITION`	`cannot delete user-secret "X": referenced by user: github_oauth/alice`	Your user record still references the secret. Remove the reference, then delete.
`PERMISSION_DENIED`	Authorization check failed	Your user-secret name does not match the `{provider}/{username}/*` pattern for your identity, or you lack the required permission.

Profiles and secrets: concept overview of developer profiles and secret scopes
secret: tenant-wide secrets shared across all developers
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources
murmur setup: CLI command that creates user-secrets automatically during onboarding
murmur secret set: CLI command for managing tenant and developer secrets
murmur secret mount: deliver one of your user-secrets to every VM you spawn
Encryption: how secrets are encrypted at rest and in transit
Permissions: default authorization bindings including the murmur-member-self grant

Getting Started

Core Concepts

Guides

Fields

Name convention

Examples

Setting a user-secret via murmur setup

Creating a user-secret manually

Listing your user-secrets

Reading a single user-secret

Deleting a user-secret

How user-secrets reach agents

Errors

​Fields

​Name convention

​Examples

​Setting a user-secret via murmur setup

​Creating a user-secret manually

​Listing your user-secrets

​Reading a single user-secret

​Deleting a user-secret

​How user-secrets reach agents

​Errors

​Related

Fields

Name convention

Examples

Setting a user-secret via murmur setup

Creating a user-secret manually

Listing your user-secrets

Reading a single user-secret

Deleting a user-secret

How user-secrets reach agents

Errors

Related