ops-warden/wiki/ActorInventoryPatterns.md

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

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

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.

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

Supervised interactive agent account (agt-custodian)

CUST-WP-0073-T02 / WARDEN-WP-0045. One principal for the dedicated host account custodian-agt on Railiance01, shared by the Codex, Claude Code and Grok Build harnesses running in the isolated workstation WSL distro custodian-agents.

agt-custodian:
  type: agt
  principals: [agt-custodian]
  ttl_hours: 12
  max_ttl_hours: 12          # --ttl cannot raise it to the 24 h agt maximum
  extensions: [permit-pty]   # clears agent/port/X11 forwarding and user-rc

• TTL 12 h. Between the attended bootstrap profile (2 h) and the agt type maximum (24 h): one supervised working session, so a leaked cert expires by the next day and every new session needs a fresh supervisor issuance. The profile ceiling (max_ttl_hours) stops a --ttl override from lengthening it.

• Extensions. permit-pty only — interactive harness shells need a pty. Agent, port and X11 forwarding and ~/.ssh/rc are not granted (-O clear locally; explicit extensions map on the Vault role, which must allow permit-pty).

• No source-address. The workstation egress IP is not stable (residential dynamic address, WSL NAT), so a pinned address would break issuance silently. Revisit if agent traffic moves to a fixed egress (VPN or bastion).

• No self-issuance. The supervisor (Bernd) signs from the operator account with warden sign agt-custodian --pubkey <agent-key>.pub > <agent-key>-cert.pub and places the cert into the custodian-agents distro. That distro gets no warden config, CA key, Vault token or warden-sign lane credential, so the signing path is not reachable from the agent account.

• Host mapping (AuthorizedPrincipalsFile for custodian-agt) is owned by railiance-infra.

• 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)

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)

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

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