Skip to main content

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.

Secrets are KMS-encrypted values stored in the catalog and injected as environment variables on agent VMs. They allow agents to access API keys, database credentials, and other sensitive values without exposing them in plaintext.

​
murmur secret set

Create or update a tenant secret. The value is read from stdin. 
murmur secret set <NAME>

# Set a secret from stdin
echo "sk-prod-abc123" | murmur secret set INTERNAL_API_KEY

# Set a secret interactively (prompts for value)
murmur secret set DATABASE_URL
# Enter secret value: ▊

# Pipe from a file
cat credentials/db-url.txt | murmur secret set DATABASE_URL
The secret name must be uppercase with underscores (e.g., INTERNAL_API_KEY, DATABASE_URL). The value is encrypted with KMS before storage — it never exists in plaintext in the catalog.

​
murmur secret ls

List all tenant secrets. Only names are shown — values are encrypted and never displayed. 
murmur secret ls

​
Example output

NAME                  UPDATED         AUTHOR
INTERNAL_API_KEY      2025-01-15      alice
DATABASE_URL          2025-01-10      bob
STRIPE_SECRET_KEY     2025-01-08      alice
SLACK_WEBHOOK_URL     2024-12-20      carol

​
murmur secret rm

Delete a tenant secret. 
murmur secret rm <NAME>

murmur secret rm OLD_API_KEY
Deleting a secret that is referenced in a workspace’s secret_refs will cause agents in that workspace to fail when they try to access the missing environment variable. Update secret_refs first.

​
Tenant vs developer secrets

Murmur supports two scopes of secrets:
ScopeCatalog kindVisibilityUse case
TenantsecretAll developers in the tenantShared API keys, database URLs, webhook tokens
Developeruser-secretOnly the developer who created itPersonal tokens, individual API keys

​
Tenant secrets

Managed via murmur secret set/ls/rm. Available to all agents spawned by any developer in the tenant. 
echo "sk-shared-key" | murmur secret set SHARED_API_KEY

​
Developer secrets

Managed via the catalog CRUD commands with the user-secret kind. Only available to agents spawned by the developer who created the secret. 
echo "sk-personal-key" | murmur set user-secret MY_PERSONAL_KEY
Developer secrets are encrypted with additional authenticated data (AAD) tied to the developer’s identity, ensuring that only the creating developer’s agents can decrypt them.

​
How secrets reach VMs

Secrets follow a secure delivery pipeline from the catalog to the agent VM: 
Catalog (KMS-encrypted)
        │
        ▼
Control Worker (KMS decrypt → NaCl re-seal)
        │
        ▼
VM Process Memory (NaCl decrypt → env vars)
  1. Storage: Secrets are encrypted with Google Cloud KMS and stored in the catalog
  2. Delivery: When an agent starts, the control worker (the only process with KMS decrypt permission) decrypts the secrets
  3. Re-sealing: The control worker re-encrypts secrets using the VM’s ephemeral X25519 public key (NaCl box encryption)
  4. Injection: The VM decrypts secrets in process memory and sets them as environment variables
  5. Cleanup: When the agent stops, secrets are destroyed with the process — they are never written to the VM filesystem

​
Environment variable mapping

Secrets are available on agent VMs as environment variables with the MURMUR_SECRET_ prefix:
Secret nameEnvironment variable on VM
INTERNAL_API_KEYMURMUR_SECRET_INTERNAL_API_KEY
DATABASE_URLMURMUR_SECRET_DATABASE_URL
STRIPE_SECRET_KEYMURMUR_SECRET_STRIPE_SECRET_KEY
Agents can access these variables in their code: 
import os
api_key = os.environ["MURMUR_SECRET_INTERNAL_API_KEY"]

apiKey := os.Getenv("MURMUR_SECRET_INTERNAL_API_KEY")

curl -H "Authorization: Bearer $MURMUR_SECRET_INTERNAL_API_KEY" https://api.example.com

​
Workspace secret_refs

For a secret to be delivered to a workspace’s agents, it must be listed in the workspace’s secret_refs: 
# .murmur/murmur.yaml or via murmur set workspace
secret_refs:
  - INTERNAL_API_KEY
  - DATABASE_URL
  - STRIPE_SECRET_KEY
Only secrets listed in secret_refs are delivered to VMs for that workspace. This prevents accidental exposure of secrets to workspaces that should not have them. 
# Add a secret reference to a workspace
murmur patch workspace backend-team --set secret_refs='["INTERNAL_API_KEY","DATABASE_URL"]'

​
Common workflows

​
Add a new shared secret

# 1. Create the secret
echo "sk-new-key-123" | murmur secret set NEW_SERVICE_KEY

# 2. Add it to the workspace's secret_refs
murmur patch workspace backend-team \
  --set secret_refs='["INTERNAL_API_KEY","DATABASE_URL","NEW_SERVICE_KEY"]'

# 3. New agents will now have MURMUR_SECRET_NEW_SERVICE_KEY available

​
Rotate a secret

# Update the secret value (same name, new value)
echo "sk-rotated-key-456" | murmur secret set INTERNAL_API_KEY

# Running agents keep the old value until restarted
# New agents get the new value automatically
# To update a running agent's credentials:
murmur rekey fix-auth-bug

​
Audit secrets

# List all tenant secrets
murmur secret ls

# See full metadata for a specific secret
murmur describe secret INTERNAL_API_KEY

​
Clean up unused secrets

# Remove the secret reference from the workspace first
murmur patch workspace backend-team --set secret_refs='["DATABASE_URL"]'

# Then delete the secret
murmur secret rm OLD_API_KEY