# Actor Inventory Patterns

Date: 2026-06-17

Standard naming and TTL patterns for `~/.config/warden/inventory.yaml` (or
Git-tracked inventory in your environment). Actor names **must** use the prefix
matching `ActorType`: `adm-`, `agt-`, `atm-`.

See `wiki/AccessManagementDirective.md` for policy background and
`examples/inventory.seed.yaml` for a copy-paste template.

---

## Naming convention

```text
<type>-<scope>-<purpose>[-<instance>]
```

| Segment | Meaning |
| --- | --- |
| `type` | `adm` \| `agt` \| `atm` |
| `scope` | team, repo, or environment slug (`codex`, `state-hub`, `ci`) |
| `purpose` | narrow function (`bridge`, `bootstrap`, `backup`) |
| `instance` | optional disambiguator (`railiance01`) |

**Examples:** `agt-state-hub-bridge`, `agt-codex-interhub-bootstrap`, `atm-nightly-backup`.

---

## Pattern catalog

### Tunnel agents (`agt`)

Used by ops-bridge `cert_command` for SSH tunnels.

```yaml
agt-state-hub-bridge:
  type: agt
  principals: [agt-task-bridge]
  ttl_hours: 24
  description: "ops-bridge tunnel to state-hub backend"
```

- One actor per tunnel identity (match `ssh_user` / `actor` in `tunnels.yaml`).
- Principal should match host `auth_principals` entry deployed by railiance-infra.
- TTL default 24 h; shorten for high-risk paths.

### Kaizen / Codex agents (`agt`)

Attended or semi-attended agent work on trusted hosts.

```yaml
agt-codex-interhub-bootstrap:
  type: agt
  principals: [agt-interhub-bootstrap]
  ttl_hours: 2
  description: "Short-lived agent access for Inter-Hub bootstrap execution"
```

- Prefer **1–2 h TTL** for bootstrap; never multi-day agent certs.
- Principal narrower than general ops access (`agt-interhub-bootstrap` not `agt-ops-full`).
- Remove or disable actor when lane is retired.
- See `wiki/InterHubBootstrapAccessLane.md`.

### Human operators (`adm`)

```yaml
adm-bernd:
  type: adm
  principals: [adm-full]
  ttl_hours: 48
  description: "Human operator — interactive shell when policy allows"
```

- Humans bring their own keypair (`ssh-keygen`); warden signs pubkey only.
- Use separate actors per person, not shared `adm-shared`.
- Principals may be narrowed (`adm-readonly`) where railiance-infra supports it.

### CI / cron automations (`atm`)

```yaml
atm-backup-daily:
  type: atm
  principals: [atm-backup-daily]
  ttl_hours: 8
  description: "Nightly backup automation — force-command on host"
```

- Lowest TTL practical (≤ 8 h per directive max).
- Principal tied to single force-command on host.
- Prefer `warden issue` only in secured CI secret store contexts.

---

## TTL guidance

| Type | Default max (warden) | Typical attended | Typical automation |
| --- | --- | --- | --- |
| `adm` | 48 h | 24–48 h | N/A |
| `agt` | 24 h | 1–4 h bootstrap | 8–24 h supervised |
| `atm` | 8 h | N/A | 1–8 h |

`warden sign` **rejects** TTL above type maximum (WARDEN-WP-0002).

---

## Principal narrowing

1. One principal per automation purpose — avoid `agt-ops-admin`.
2. Match host-side `auth_principals` exactly — coordinate with railiance-infra before add.
3. Document `description` field for audit and scorecard reviews.
4. Use `hosts:` section in inventory for reference (not enforced by warden).

---

## Adding a new worker

```bash
warden inventory add agt-myrepo-ci \
  --type agt \
  --principal agt-myrepo-ci \
  --ttl 4 \
  --description "CI deploy actor for myrepo"
warden inventory list
warden sign agt-myrepo-ci --pubkey /path/to/ci.pub
```

Copy patterns from `examples/inventory.seed.yaml` before inventing new names.

---

## Anti-patterns

| Do not | Why |
| --- | --- |
| Reuse `adm` actor for agents | Breaks attribution; use `agt-*` |
| Store private keys in inventory YAML | Inventory is registry only — keys live in secure paths |
| 72 h `agt` cert for convenience | Violates TTL policy and directive |
| One `agt-ops` for all tunnels | Cannot revoke or audit per tunnel |
| Put API keys in inventory | Route to OpenBao — `wiki/CredentialRouting.md` |