secret

A secret is a catalog resource that stores a sensitive value for your tenant, such as an API key, access token, or credential. Secrets are encrypted at rest. A workspace delivers a secret to its agent VMs when it lists the secret in runtime_secret_mounts, as an environment variable or a file. Secret values are write-only. You can set and delete them, but you cannot read them back. Listing secrets returns names and metadata only.

Fields

Name	Type	Required	Description
`workspace_use`	object	no	For tenant-level names, which workspaces may use this resource: `scope` is `WORKSPACE_USE_SCOPE_NONE` (default), `WORKSPACE_USE_SCOPE_ALL`, or `WORKSPACE_USE_SCOPE_SELECTED` with a `workspaces` list. Scoped names carry no policy and are usable only in their own workspace. See resource admission.
`name`	string	yes	Bare secret name matching `[A-Z][A-Z0-9_]*`, or `{workspace}/{SECRET_NAME}` with a lowercase DNS-label workspace prefix. The prefix must name an existing workspace.
`plaintext_value`	bytes	yes (on write)	The secret value, base64-encoded in YAML. Write-only: cleared after encryption and never returned by reads or listings.
`declared_kind`	string	no	What the credential is, for example `github.pat_fine_grained`. Enables a shape check and an identifying hint. Write-only. Run `murmur secret set --help` for the kinds Murmur knows.
`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 (read-only)	Timestamp of the last update. Set automatically.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.

An environment-variable mount (MOUNT_TYPE_ENV) delivers the secret under its own name unless the mount sets env_name. A secret named NPM_TOKEN mounted this way is available to agents as $NPM_TOKEN.

Reserved names

Two categories of names are rejected:

Pattern	Reason
`MURMUR_*`	Reserved for internal use. Any name starting with `MURMUR_` is rejected.
`GH_TOKEN`	Automatically populated from the spawning developer’s GitHub token. Cannot be set or deleted as a tenant secret.

CLI shorthand

The murmur secret set commands provide a shorthand for managing secrets without constructing catalog payloads manually.

Command	Description
`murmur secret set`	Set a secret. Stores stdin’s exact bytes. `--kind` sets `declared_kind`.
`murmur secret ls`	List secrets with each one’s kind and hint.
`murmur secret rm`	Delete a secret.

Examples

Setting a secret

Pipe the value through stdin. The command stores stdin’s exact bytes, so use printf rather than echo to avoid a trailing newline:

printf 'sk-ant-abc123' | murmur secret set ANTHROPIC_API_KEY

Set secret "ANTHROPIC_API_KEY"

Setting a secret with a description

Using the catalog API directly. plaintext_value is base64-encoded (ZGQtYWJjMTIz is dd-abc123):

cat <<'EOF' | murmur set secret DATADOG_API_KEY
name: DATADOG_API_KEY
plaintext_value: ZGQtYWJjMTIz
description: "Datadog API key for agent metrics"
EOF

Listing secrets

murmur secret ls

NAME               KIND               HINT
ANTHROPIC_API_KEY  anthropic.api_key  …9xQ
DATADOG_API_KEY    —                  —
NPM_TOKEN          —                  —

A secret set with --kind shows its kind. When the value matches the kind’s expected shape, it also shows a short identifying hint. A secret stored without a declared kind shows dashes.

Deleting a secret

murmur secret rm NPM_TOKEN

Deleted secret "NPM_TOKEN"

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`secret name "foo" must match [A-Z][A-Z0-9_]*`	Use uppercase letters, digits, and underscores only. The name must start with a letter.
`INVALID_ARGUMENT`	`secret name "MURMUR_X" is reserved (MURMUR_* is internal)`	Choose a name that does not start with `MURMUR_`.
`INVALID_ARGUMENT`	`secret name "GH_TOKEN" is reserved — it is automatically populated from the developer profile`	`GH_TOKEN` is provided automatically. You do not need to set it.
`INVALID_ARGUMENT`	`plaintext_value is required`	The write request is missing the secret value. Provide `plaintext_value`.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit (N bytes)`	Shorten the `description` field to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`secret name "GH_TOKEN" is reserved and cannot be deleted`	Reserved secrets cannot be deleted.
`INVALID_ARGUMENT`	`descriptor is server-populated — set declared_kind instead`	Remove `descriptor` from the payload. Set `declared_kind` instead.
(CLI)	`secret value must be piped via stdin`	`murmur secret set` refuses a terminal on stdin. Pipe the value in.

Profiles and secrets: concept overview
Workspaces: the resource whose agents receive tenant secrets
murmur secret set: CLI commands for managing secrets
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Fields

Reserved names

CLI shorthand

Examples

Setting a secret

Setting a secret with a description

Listing secrets

Deleting a secret

Errors

​Fields

​Reserved names

​CLI shorthand

​Examples

​Setting a secret

​Setting a secret with a description

​Listing secrets

​Deleting a secret

​Errors

​Related

Fields

Reserved names

CLI shorthand

Examples

Setting a secret

Setting a secret with a description

Listing secrets

Deleting a secret

Errors

Related