Documentation Index
Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
Use this file to discover all available pages before exploring further.
A user-secret is a catalog resource that holds one encrypted value scoped to a single developer. Unlike a tenant-wide secret, a user-secret is bound to the developer who created it — only agents that developer spawns receive it.
User-secrets are created automatically by murmur setup when you onboard your credentials. You can also create and update them manually with murmur set.
Fields
| Name | Type | Required | Description |
|---|
name | string | yes | Secret name. Must be non-empty. Names created by murmur setup follow the convention {provider}/{username}/{SECRET_NAME} (e.g. github_oauth/alice/GH_TOKEN). |
plaintext_value | bytes | yes (on write) | Secret value. Write-only — cleared after encryption and never returned by read or list operations. |
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, created_at, and description — never the encrypted value. Name convention
The default authorization rules grant each developer read, create, edit, and list access to user-secrets matching the pattern {provider}/{username}/*. 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 |
{provider}/{username}/{NAME} convention so the authorization pattern matches.
Examples
Setting a user-secret via murmur setup
murmur setup creates user-secrets automatically as part of onboarding:
This encrypts your GitHub token, signing key, and any configured API keys as user-secrets under your identity prefix.
Creating a user-secret manually
echo '{"name":"github_oauth/alice/CUSTOM_KEY","plaintext_value":"c2stY3VzdG9tLWtleQ=="}' \
| murmur set user-secret github_oauth/alice/CUSTOM_KEY
Listing your user-secrets
NAME
github_oauth/alice/GH_TOKEN
github_oauth/alice/ANTHROPIC_API_KEY
github_oauth/alice/SIGNING_KEY
Reading a single user-secret
murmur get user-secret github_oauth/alice/GH_TOKEN
name, created_at, and description. The encrypted value is stripped.
Deleting a user-secret
murmur rm user-secret github_oauth/alice/CUSTOM_KEY
Deleting a user-secret that your user record references (e.g. github_token_secret) causes agents you spawn to start without that credential. Run murmur setup again to re-create it. How user-secrets reach agents
When you spawn an agent, the system reads your user record, resolves each referenced user-secret name, and includes the encrypted values in the agent’s launch payload. The well-known secret names 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 |
signing_key_secret | github_oauth/alice/SIGNING_KEY | SIGNING_KEY |
claude_token_secret | github_oauth/alice/CLAUDE_TOKEN | CLAUDE_TOKEN |
claude_refresh_token_secret | github_oauth/alice/CLAUDE_REFRESH_TOKEN | CLAUDE_REFRESH_TOKEN |
openai_api_key_secret | github_oauth/alice/OPENAI_API_KEY | OPENAI_API_KEY |
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 | 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. |
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 resourcesmurmur get — CLI command for reading catalog resourcesmurmur setup — CLI command that creates user-secrets automatically during onboarding- Secrets management — CLI guide for managing tenant and developer secrets
- Encryption — how secrets are encrypted at rest and in transit
- Permissions — default authorization bindings including the
user-secrets-self grant
