> ## 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.

# secret

> Catalog resource that stores an encrypted tenant-wide secret, decrypted on agent VMs and delivered as an environment variable at runtime.

A [secret](/concepts/secrets) is a catalog resource that stores a sensitive value — an API key, access token, or credential — for your tenant. [Secrets](/concepts/secrets) are encrypted at rest and injected as environment variables on every agent VM in the tenant's [workspaces](/concepts/workspaces).

[Secret](/concepts/secrets) values are write-only. You can set and delete them, but you cannot read them back. Listing [secrets](/concepts/secrets) returns names and metadata only.

## Fields

| Name              | Type      | Required       | Description                                                                                                     |
| ----------------- | --------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `name`            | string    | yes            | Secret name. Must match `[A-Z][A-Z0-9_]*` — uppercase letters, digits, and underscores, starting with a letter. |
| `plaintext_value` | bytes     | yes (on write) | The secret value. Write-only — cleared after encryption and never returned by reads or listings.                |
| `created_at`      | timestamp | no (read-only) | Timestamp of when the secret was created. Set automatically on creation.                                        |
| `description`     | string    | no             | Human-readable description shown in the dashboard. Maximum 1024 bytes.                                          |

<Note>
  The `name` field doubles as the environment variable name on agent VMs. A [secret](/concepts/secrets) named `NPM_TOKEN` is available to agents as `$NPM_TOKEN`.
</Note>

## 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](/concepts/secrets). |

## CLI shorthand

The [`murmur secret set`](/cli/secret-set) commands provide a shorthand for managing [secrets](/concepts/secrets) without constructing catalog payloads manually.

| Command                                | Description                                                    |
| -------------------------------------- | -------------------------------------------------------------- |
| [`murmur secret set`](/cli/secret-set) | Set a [secret](/concepts/secrets). Reads the value from stdin. |
| [`murmur secret ls`](/cli/secret-ls)   | List all [secret](/concepts/secrets) names.                    |
| [`murmur secret rm`](/cli/secret-rm)   | Delete a [secret](/concepts/secrets).                          |

## Examples

### Setting a secret

Pipe the value through stdin:

```bash theme={null}
echo "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:

```bash theme={null}
cat <<'EOF' | murmur set secret DATADOG_API_KEY
{
  "name": "DATADOG_API_KEY",
  "plaintext_value": "dd-abc123",
  "description": "Datadog API key for agent metrics"
}
EOF
```

### Listing secrets

```bash theme={null}
murmur secret ls
```

```
ANTHROPIC_API_KEY
DATADOG_API_KEY
NPM_TOKEN
```

### Deleting a secret

```bash theme={null}
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`                                                           | Shorten the `description` field to 1024 bytes or fewer.                                 |
| `INVALID_ARGUMENT` | `secret name "GH_TOKEN" is reserved and cannot be deleted`                                      | Reserved [secrets](/concepts/secrets) cannot be deleted.                                |

## Related

* [Profiles and secrets](/concepts/secrets) — concept overview
* [Workspaces](/concepts/workspaces) — the resource whose agents receive tenant [secrets](/concepts/secrets)
* [`murmur secret set`](/cli/secret-set) — CLI commands for managing [secrets](/concepts/secrets)
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources