HEE-PVE-DEPLOY(8) HEE Tools HEE-PVE-DEPLOY(8)
NAME
hee-pve-deploy - deploy and provision a Proxmox LXC from one declarative
manifest
SYNOPSIS
hee-pve-deploy [-h] [--node NODE] [--host HOST] [--dry-run]
hee-pve-deploy MANIFEST.yaml [--node pve] [--host 10.0.0.153] [--dry-run]
[--reprovision] [--anchors FILE] [--addons FILE] [--agent-roster FILE]
positional arguments:
manifest pve/services/<name>.yaml -- see the manifest format
above
options:
-h, --help show this help message and exit
--node NODE
--host HOST
--dry-run resolve the manifest and print every command that
would run -- create, add-ons, files, provision --
creating and changing nothing. Without it the deploy
is applied.
--reprovision on a hostname that ALREADY EXISTS: re-ship every
'files:' entry (sha256-compared against the container
first and reported new/changed/unchanged) and re-run
every 'provision:' script, instead of the idempotent
skip -- exits with provision:'s own exit code. Never
runs 'pct set': a live mounts:/features: mismatch
against the manifest is printed as a WARNING naming
the pct set it would take, and nothing is applied --
that still needs a destroy and a create. On a hostname
that does NOT exist yet this flag is a no-op: a plain
create happens, same as without it.
--anchors ANCHORS registry of roles whose address may be pinned. A
manifest that declares address or hwaddr must name a
role listed there; anything else has its address
allocated.
--addons ADDONS the org's container-addons registry, the only place an
'addons:' name resolves. Unreadable means every add-on
is refused, never silently skipped.
--agent-roster AGENT_ROSTER
the org's signed agent roster, the only place a model
is named. Read only by 'generate: agent-roster-model'
files entries; it must be ratified and its .asc must
verify, or nothing is rendered.
DESCRIPTION
[--reprovision] [--anchors ANCHORS] [--addons ADDONS]
[--agent-roster AGENT_ROSTER]
manifest
hee-pve-deploy -- deploy and provision a Proxmox LXC from one declarative manifest.
One YAML file per service; this tool creates the container via the real
Proxmox API (pvesh over SSH to the node), idempotent by hostname, then
applies the manifest's add-ons, files and provision scripts inside it.
Real trigger (2026-08-24, Spencer): "build extensible deploy via api to
pve strat" -- tiny, bare-minimum LXC per core service (bastion, qmail
MTA, snmpd), matching docs/guides/PVE_CAPACITY_PLANNING_METHODOLOGY.md's
step 5 ("a new service is a new manifest entry, not new deploy code").
Never installs anything on the pve host itself -- pvesh is Proxmox's
own real API-wrapper CLI, already there on any real Proxmox node; this
tool just calls it over SSH from wherever hee runs.
Manifest format (pve/services/<name>.yaml):
hostname: bastion
template: alpine-3.23-default_20260116_amd64.tar.xz
cores: 1
memory_mb: 256
disk_gb: 4
storage: ssd1
bridge: vmbr0
unprivileged: true
onboot: 1 # start on host boot. DEFAULTS TO 1 here, unlike Proxmox's own 0
features: {nesting: true, keyctl: true} # pve LXC features; only for a container that runs containers
addons: [agent-tooling] # named apk sets from the org's registry (--addons)
agent: ci-triage # agent roster role, only for a container that runs an agent
files: # committed files pushed INTO the container
- {src: pve/lab-dhcp/dnsmasq.conf, dst: /etc/dnsmasq.conf, mode: "0644"}
- {src: tools/meme-factory, dst: /opt/meme-factory} # a committed DIRECTORY, shipped as one tar
- {generate: agent-roster-model, dst: /etc/claude-code/managed-settings.d/50-model.json, mode: "0644"}
provision: # committed POSIX sh scripts run inside it
- pve/lab-dhcp/provision.sh
resolver: # the container's /etc/resolv.conf, and nothing overwrites it
nameservers: [10.0.0.194, 10.0.0.72]
search: [lab.tcos.us, tcos.us]
ndots: 2
mounts: # directories of the pve HOST lent to the container (bind mounts)
- {host: /srv/storage, ct: /data/storage} # read-write
- {host: /srv/media, ct: /data/media, ro: true} # read-only
`files:` and `provision:` paths are relative to the root of the repo the
manifest lives in (git rev-parse --show-toplevel), never to the current
directory and never absolute. A `src` that is a directory is shipped whole:
every file git tracks under it (`git ls-files`, so nothing untracked, no
results/, no .git) goes over as one tar and is unpacked at `dst`. Real
trigger (2026-09-19): the meme-factory service is a tree in a PRIVATE repo,
and a container holds no repository credential, so the deploy is the only
honest way the code gets there; the previous shape was a hand `pct push` per
file or a clone with a credential the container must not have. `mode` is
refused on a directory entry (git's own modes travel in the tar): a manifest names what it ships, and what it
ships is under review beside it. Real trigger (2026-09-10): the only
precedent for configuring what runs INSIDE a container was a README of
`pct exec N -- sh -c "cat > /etc/..."` one-liners (fleet-ops
pve/snmp-joe/README.md) -- the same imperative shape pve/network.yaml was
written to remove for bridges. Order: create -> addons -> files ->
provision. The manifest is fully resolved BEFORE the container is created,
so a missing file fails closed rather than leaving a half-provisioned
container behind. Every step is previewed under --dry-run, including
addons, which the dry run used to skip.
A `files:` entry names either `src` (a committed file) or `generate` (a
file rendered at deploy time, never committed). The one generator today is
`agent-roster-model`: it reads the org's agent roster (--agent-roster), refuses unless
the agent roster is `status: ratified` AND its detached signature verifies with a
key the agent roster's own ratification_evidence names, then renders the
Claude Code managed-settings drop-in that pins the manifest's `agent:` to
the model the agent roster assigns. Real trigger (2026-09-10): the first agent
manifests shipped five hand-kept managed-settings.json copies, each
restating a model the signed agent roster already names -- a second source that
would leave every container on the old model after an agent roster change, with
nothing to say so. Operator: "generate from roster at deploy is correct,
footgun". The model is named in exactly one place, and the dry run prints
the rendered file.
Every command run inside the container gets
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin. `pct exec`
otherwise passes PVE's own /sbin:/bin:/usr/sbin:/usr/bin, which has no
/usr/local/bin, so a provision script calling a tool it just linked there
exited 127 (measured 2026-09-10).
`resolver:` declares the container's DNS: up to three IPv4 nameservers, in
order; an optional search list; and ndots (default 1). The tool writes
/etc/resolv.conf from it right after the network is up, before add-ons, and
makes it stick. Nothing else does, measured 2026-09-10: the golden template
sets no resolver, pve rewrites /etc/resolv.conf from the HOST's file at every
container start, and Alpine's udhcpc rewrites it from DHCP on every lease --
ct113 was resolving through 10.0.0.72 and 1.1.1.1 handed out by the
household router, and a public resolver answers NXDOMAIN for lab names. So
it also writes /etc/.pve-ignore.resolv.conf (pve skips the file), and for a
DHCP container /etc/udhcpc/udhcpc.conf with RESOLV_CONF="no". ndots matters
on musl: the search list is used only when a name has FEWER dots than
ndots, so `view.lab` (one dot) resolves as view.lab.tcos.us only with
ndots 2. Operator: "proper search and ndot settings too (view.lab/foo should
work)".
`mounts:` lends a directory of the pve HOST to the container, rendered as
`-mpN host,mp=ct[,ro=1]` in manifest order. It is the only way an
unprivileged LXC gets shared storage: the container cannot mount NFS
itself, so the host mounts or serves the storage and bind-mounts the
directory in. Real trigger (2026-09-18): the meme-factory service needs the
lab's $MNTPATH (/data/storage) inside its container, and ipk-factory has
waited since 2026-09-03 for "the nfs share once set up" -- with no field,
both would have been a hand `pct set`, the imperative shape this tool exists
to remove. Rules: both paths absolute and normalized (no trailing slash, no
`..`), no comma or `=` in either (pve's option syntax), `ct` never `/`, no
two entries with the same `ct`. Known and not hidden: in an unprivileged
container the host's uids are shifted (host uid N appears as 100000+N), so
files owned by ordinary host users read as nobody:nogroup -- reading needs
the world-read bit, writing needs a world-writable (1777) or
100000-range-owned directory on the host, and this tool chmods nothing.
pve accepts a bind mount only from root@pam, which pvesh over ssh to root
is. A bind mount is never part of a container backup.
`--reprovision` on a hostname that already exists re-ships every `files:`
entry through the identical apply_files() a create uses (directory entries
via the same `git archive HEAD` tar) and re-runs every `provision:` script,
in place of the plain idempotent skip. Real trigger,
human-execution-engine#760 (2026-09-19): the only tool path for the normal
case -- a `provision:` bug found after the container exists -- was `scp`
the fix to the node and `pct exec` it in by hand, the exact one-liner shape
this tool exists to retire, on the one flow it had no answer for. It
resolves the manifest fully first, exactly like create, and NEVER runs
`pct set`: it cannot touch the container's config, so it cannot touch the
MAC a DHCP reservation is keyed on or a mount -- those still need a destroy
and a create. Each `files:` entry is sha256-compared against what a
`pct exec VMID -- sha256sum` finds already in the container (a directory
entry compares every file the tar carries, by path relative to `dst`) and
reported `new`/`changed`/`unchanged` before it is re-shipped, and the
tool's own exit code is `provision:`'s own. A live `mounts:`/`features:`
that no longer matches the manifest (`pct config VMID`) is printed as a
`WARNING` naming the exact `pct set` that would fix it -- computed, never
run. On a hostname that does not exist yet, `--reprovision` is a no-op: a
plain create happens, same as without it.
EXAMPLES
(None marked "# ci": even --dry-run reads the live Proxmox host over ssh to
diff against the manifest, which a CI runner cannot reach.)
hee-pve-deploy pve/services/bastion.yaml --dry-run
Preview a create: every command, every file, every provision script --
nothing runs.
hee-pve-deploy pve/services/bastion.yaml
Create it for real. Idempotent by hostname: run again unchanged and it
only reports the existing container.
hee-pve-deploy pve/services/meme-factory.yaml --reprovision --dry-run
Preview a reprovision on an EXISTING container: the sha256 diff of
every files: entry (new/changed/unchanged), the mounts:/features:
WARNING if the live config has drifted from the manifest, and the
provision: scripts that would run. Nothing is applied.
hee-pve-deploy pve/services/meme-factory.yaml --reprovision
Re-ship files:, re-run provision:, on a container that already
exists. Exit code is provision:'s own. Never touches mounts:/
features: -- those still need a destroy and a create.
HEE-PVE-DEPLOY(8)