# Secrets

Layers declare keys. The image holds the manifest, not the tokens.

```
secrets.API_TOKEN = {
  description = "What this key is for";
  required = true;
  secret = true;
};
secrets.API_HOST = {
  description = "Non-secret default";
  required = false;
  default = "example.com";
};
```

## Fields

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| description | string | required | Human-readable purpose. |
| required | bool | `false` | Required on the layer default profile. |
| default | null or string | `null` | Optional default. Use for non-secret config such as a host. |
| secret | bool | `false` | When the secretGuard layer is composed, unprivileged processes see a fake. Set true only when that layer is in the compose list. |

## Invariants

- The image holds the manifest, not the tokens. Injected at process start.
- Session processes start with a cleared environment.
- `RIG_BWRAP_KEEP_ENV=1` keeps the host environment.
- `rig shell --raw-secrets` skips the secret wrap.

## Failure modes

- `rig secrets <agent>` runs `secretspec check` against the catalog agent.
- Catalog `session create` refuses when required keys are empty.
- Pulled images skip that CLI check.

## How to check

Needs a workspace.

```
rig secrets notes
```

## Related

- Layer `secrets` and `privileged`: https://rig.slopkit.dev/raw/layer.md
- `rig secrets` and `rig session`: https://rig.slopkit.dev/raw/cli.md