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

# user-secret

> Catalog resource that stores a per-developer encrypted secret, delivered only to agents spawned by its owner — for personal API tokens and keys.

A [user-secret](/concepts/secrets) is a catalog resource that holds one encrypted value scoped to a single developer. Unlike a tenant-wide [secret](/catalog/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`](/cli/setup) when you onboard your credentials. You can also create and update them manually with [`murmur set`](/cli/set).

## Fields

| Name              | Type      | Required       | Description                                                                                                                                                                     |
| ----------------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | string    | yes            | Secret name. Must be non-empty. Names created by [`murmur setup`](/cli/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.                                                                                                                                                     |

<Note>
  The `plaintext_value` field is write-only. When you read a [user-secret](/concepts/secrets) back with [`murmur get`](/cli/get), the response contains `name`, `created_at`, and `description` — never the encrypted value.
</Note>

## Name convention

The default authorization rules grant each developer read, create, edit, and list access to [user-secrets](/concepts/secrets) matching the pattern `{provider}/{username}/*`. The [`murmur setup`](/cli/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`       |

When creating [user-secrets](/concepts/secrets) manually, use the same `{provider}/{username}/{NAME}` convention so the authorization pattern matches.

## Examples

### Setting a user-secret via murmur setup

[`murmur setup`](/cli/setup) creates [user-secrets](/concepts/secrets) automatically as part of onboarding:

```bash theme={null}
murmur setup
```

This encrypts your GitHub token, signing key, and any configured API keys as [user-secrets](/concepts/secrets) under your identity prefix.

### Creating a user-secret manually

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

### Listing your user-secrets

```bash theme={null}
murmur get user-secret
```

```
NAME
github_oauth/alice/GH_TOKEN
github_oauth/alice/ANTHROPIC_API_KEY
github_oauth/alice/SIGNING_KEY
```

### Reading a single user-secret

```bash theme={null}
murmur get user-secret github_oauth/alice/GH_TOKEN
```

The response includes `name`, `created_at`, and `description`. The encrypted value is stripped.

### Deleting a user-secret

```bash theme={null}
murmur rm user-secret github_oauth/alice/CUSTOM_KEY
```

<Warning>
  Deleting a [user-secret](/concepts/secrets) that your [user](/concepts/secrets) record references (e.g. `github_token_secret`) causes agents you spawn to start without that credential. Run [`murmur setup`](/cli/setup) again to re-create it.
</Warning>

## How user-secrets reach agents

When you spawn an agent, the system reads your [user](/concepts/secrets) record, resolves each referenced [user-secret](/concepts/secrets) 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](/concepts/secrets) name does not match the `{provider}/{username}/*` pattern for your identity, or you lack the required permission. |

## Related

* [Profiles and secrets](/concepts/secrets) — concept overview of developer profiles and secret scopes
* [secret](/catalog/secret) — tenant-wide secrets shared across all developers
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources
* [`murmur setup`](/cli/setup) — CLI command that creates [user-secrets](/concepts/secrets) automatically during onboarding
* [Secrets management](/cli/secret-set) — CLI guide for managing tenant and developer secrets
* [Encryption](/security/encryption) — how secrets are encrypted at rest and in transit
* [Permissions](/security/permissions) — default authorization bindings including the `user-secrets-self` grant