# Runbook — provisioning a customer guest (operator notes)

> Operational guardrails for `--selftest=provision` / bring-up on a Felhom host. The mechanics live in
> `felhom-agent` (RUNBOOK-provisioning-storage.md + the selftest flags); this runbook records the
> operator-side decisions those mechanics assume.

## Picking the provision `-vmid` (F3 — campaign pool-effects)

**Pick the vmid from the host's FULL guest list, never from the hub inventory.**

On the node, as root:

```
pct list; qm list
```

Why this is load-bearing (CAMPAIGN-pool-effects-2026-07-01, F3): the agent's token is pool-scoped, so
the hub's per-host guest inventory contains ONLY the Felhom-pool guests. On a shared box (the
colleague's-box model), other guests — another customer's, spike/golden/scratch guests — are invisible
in the hub view, and there is deliberately NO automatic vmid assignment anywhere (agent or hub): the
operator-supplied `-vmid` is the only source. A vmid picked from the hub view can therefore collide
with an existing, hub-invisible guest.

What happens on a collision (belt-and-suspenders, agent >= v0.60.0): PVE refuses the restore
("CT <vmid> already exists"), the agent arms NO destroy (proof-of-launch gating — it never destroys a
guest the transaction didn't create), and the provision fails cleanly. So a collision is safe — but it
is still a failed provision and an ERROR in the logs; pick from `pct list` + `qm list` and it never
happens.

Reserved — never provision on these (the agent refuses them):
- `9999` — standing selftest scratch
- `990000–990009` — restore-test scratch band, **reserved fleet-wide on every Felhom host**: a foreign
  guest parked in this band forces the self-restore-test to advance around it (agent >= v0.60.0) and,
  if the band fills, to skip entirely.

## Related

- Storage/sizing flags: `felhom-agent/RUNBOOK-provisioning-storage.md`
- Pool + scoped-ACL model: `documentation/audits/SPIKE-pool-scoped-acl-2026-07-01.md`
- Collision/pool-blindness analysis: `documentation/audits/CAMPAIGN-pool-effects-2026-07-01.md`
