hosts, vm, lxc¶

The inventory. hosts: holds the machines labops reaches directly; a host with hypervisor: proxmox nests its guests underneath as vm: and lxc:, so the one block describes the whole tree.

The three node kinds share most of their fields. Where they differ is how they are reached: a host or VM over SSH, a container through its Proxmox parent with pct exec — which is why an LXC needs no sshd, no credentials of its own and no route from the machine running labops.

The key you write a node under is its name, unless the node sets name itself. That name becomes a DNS label once settings.dns is configured, so it must be a legal one — no underscores — unless dns_name overrides it.

Any node may be marked os: unmanaged. It is then tracked, resolved and proxied like any other, but setup and update skip it: an appliance OS or a box you do not own has no package manager for labops to drive.

Host¶

A top-level node under hosts: — anything labops reaches directly.

A bare-metal box, an appliance you only want tracked, or a Proxmox node whose guests hang off it as vm: and lxc:. The key you write in hosts: is the node's name, and it becomes a DNS label when settings.dns is configured, so it must be a legal one (no underscores) unless dns_name overrides it.

Key	Type	Default	Description
`name`	string	`""`	Overrides the key this node is written under. Leave it unset — the usual case — and the key is the name. Set it when the key is not the name you want to target and publish, e.g. a key that is not a legal DNS label. Must be unique across the config either way.
`hypervisor`	`none` \| `proxmox`	`"none"`	`proxmox` unlocks the `vm:` and `lxc:` blocks and makes this node the parent that guest commands run through. `none`, the default, is a node that hosts no guests labops manages.
`os`	`debian` \| `alpine` \| `redhat` \| `unmanaged`	required	Picks the package manager used to update this node: `debian` (apt), `alpine` (apk) or `redhat` (dnf). Use `unmanaged` for anything labops should not provision or patch — an appliance, an unsupported distro, or a box you do not own. Unmanaged nodes are still listed, resolved and proxied.
`ip`	IPv4 address	required	The address labops connects to, and the address published for this node's DNS records and proxy routes.
`creds`	Creds	unset	Credentials for this node only. Omit to use `settings.default_creds`.
`tags`	list of string	empty	Free-form labels, matched by `labops update --tag`. Tags are local to the node that carries them — a guest does not inherit its parent's tags, so use `--under` to sweep a whole subtree.
`lxc`	map of name → LXC	unset	Proxmox containers on this node, keyed by name. Requires `hypervisor: proxmox`.
`vm`	map of name → VM	unset	Proxmox virtual machines on this node, keyed by name. Requires `hypervisor: proxmox`.
`docker`	Docker	unset	Docker Compose stacks running on this node.
`web_services`	list of WebService or map of name → integer	unset	HTTP services this node exposes. Each entry with a `proxy_name` becomes a route in the generated Caddyfile.
`dns`	boolean	`true`	Set `false` to keep this node out of DNS entirely — tracked in the config, never published to Pi-hole.
`dns_name`	list of string	unset	Publish this node under a different label than its key, or under several: a list yields one record per name, all pointing at the same address. A node with `dns_name` is exempt from the rule that its key must be a legal DNS label.
`mac`	string	unset	The NIC that listens for a Wake-on-LAN magic packet, needed by `labops wake`. Colon, dash and dotted notation are all accepted. A magic packet goes to the broadcast address, which routers do not forward, so run labops on the same segment or relay it with `wake --via`.

VM¶

A Proxmox virtual machine, written under a proxmox node's vm: block.

Unlike a container, a VM is reached over SSH like an ordinary host, so it behaves the same as a hosts: entry apart from carrying a vmid and belonging to a parent. An appliance OS that labops cannot provision — HomeAssistant OS is the standing example — is still a VM, written with os: unmanaged.

Key	Type	Default	Description
`name`	string	`""`	Overrides the key this VM is written under. Leave it unset — the usual case — and the key is the name. Set it when the key is not the name you want to target and publish, e.g. a key that is not a legal DNS label. Must be unique across the config either way.
`hypervisor`	`none` \| `proxmox`	`"none"`	`proxmox` if this guest is itself a Proxmox node with guests of its own (nested virtualisation), which is what unlocks the `lxc:` and `vm:` blocks below. Otherwise leave it.
`os`	`debian` \| `alpine` \| `redhat` \| `unmanaged`	required	Picks the package manager used to update this VM: `debian` (apt), `alpine` (apk) or `redhat` (dnf). Use `unmanaged` for an appliance OS labops cannot patch or SSH-provision — it stays listed, resolved and proxied, but setup/update skip it.
`ip`	IPv4 address	required	The address labops connects to over SSH, and the address published for this VM's DNS records and proxy routes.
`vmid`	integer	required	The Proxmox VM ID. Used to start the guest (`qm start <vmid>` on the parent) and to address it by number, so it must match Proxmox and be unique across the guests of one host.
`creds`	Creds	unset	Credentials for this VM only. Omit to use `settings.default_creds`.
`tags`	list of string	empty	Free-form labels, matched by `labops update --tag`. Not inherited from the parent host.
`lxc`	map of name → LXC	unset	Containers on this VM, when it is itself a Proxmox node. Keyed by name. Requires `hypervisor: proxmox`.
`vm`	map of name → VM	unset	Virtual machines on this VM, when it is itself a Proxmox node. Keyed by name. Requires `hypervisor: proxmox`.
`web_services`	list of WebService or map of name → integer	unset	HTTP services this VM exposes. Each entry with a `proxy_name` becomes a route in the generated Caddyfile.
`docker`	Docker	unset	Docker Compose stacks running on this VM.
`dns`	boolean	`true`	Set `false` to keep this VM out of DNS entirely.
`dns_name`	list of string	unset	Publish this VM under a different label than its key, or under several. Also exempts the key from having to be a legal DNS label.
`mac`	string	unset	Not needed to wake a guest: `labops wake` runs `qm start <vmid>` on the parent, because a magic packet cannot start a stopped VM — nothing inside it is listening, and Proxmox does not watch for WoL on a guest's behalf. Set this only if the VM has a NIC of its own that really does wake, then ask for it with `wake --packet`.

LXC¶

A Proxmox container, written under a proxmox node's lxc: block.

Containers are never reached over SSH: labops runs commands on the Proxmox parent and enters the container with pct exec. So an LXC needs no sshd and no route from the machine running labops — only a vmid and a reachable parent. That is also why creds here is rarely needed.

Key	Type	Default	Description
`name`	string	`""`	Overrides the key this container is written under. Leave it unset — the usual case — and the key is the name. Set it when the key is not the name you want to target and publish, e.g. a key that is not a legal DNS label. Must be unique across the config either way.
`ip`	IPv4 address	required	The container's address, published for its DNS records and proxy routes. Not used to connect — that goes through the Proxmox parent.
`os`	`debian` \| `alpine` \| `redhat` \| `unmanaged`	required	Picks the package manager used to update this container: `debian` (apt), `alpine` (apk) or `redhat` (dnf). Use `unmanaged` to keep it listed and routable but never patched.
`vmid`	integer	required	The Proxmox container ID. This is how labops addresses it — `pct exec <vmid>` on the parent — so it must match Proxmox, and it must be unique across the guests of one host.
`creds`	Creds	unset	Credentials for this container only. Rarely needed: labops reaches it through the Proxmox parent, whose credentials are what matter.
`tags`	list of string	empty	Free-form labels, matched by `labops update --tag`. Not inherited from the parent host — a container is only `prod` if it says so.
`web_services`	list of WebService or map of name → integer	unset	HTTP services this container exposes. Each entry with a `proxy_name` becomes a route in the generated Caddyfile.
`docker`	Docker	unset	Docker Compose stacks running in this container.
`dns`	boolean	`true`	Set `false` to keep this container out of DNS entirely.
`dns_name`	list of string	unset	Publish this container under a different label than its key, or under several. Also exempts the key from having to be a legal DNS label.
`mac`	string	unset	Rarely useful here: a stopped container has nothing listening for a magic packet, so `labops wake` starts it with `pct start` on the parent instead. Set this only if the container really does own a NIC that wakes, and ask for it with `wake --packet`.