settings

Everything that is not a machine. Nothing here is required: default_creds is needed only once some node labops manages has no creds of its own, and the dns and proxy blocks are subsystems you opt into — leaving one out simply means the matching commands have nothing to act on and say so.

Settings

Everything that is not a node: credentials, the secret store, and the optional DNS, proxy and target-set subsystems.

Nothing here is required. Leaving dns or proxy out does not disable a feature you were using — it means the corresponding commands have nothing to act on and say so, rather than guessing.

Key	Type	Default	Description
default_creds	Creds	unset	Credentials used for every node that does not carry its own creds. Required only when some node labops manages (os other than unmanaged) has no creds of its own — a render-only or DNS-only config never connects to anything and so needs none. YamlRoot enforces that, because it is the only place that can see both.
env_file	path to a file	unset	The secret store labops reads API tokens from. Defaults to a .env next to the config file; set this to point elsewhere, relative to the config file or absolute. labops only ever reads it, and it is git-ignored.
dns	Dns	unset	Local DNS, published to Pi-hole v6. Omit to leave the dns commands with nothing to do.
proxy	Proxy	unset	The Caddy reverse proxy. Omit to leave the proxy commands with nothing to do; web_services entries are then tracked but not routed.
targets	map of name → Selector	empty	Named, reusable selections for labops update <name> — the same four filters as the CLI options. Put the sweeps you run often here instead of retyping them.

Creds

SSH credentials, either as settings.default_creds or per node.

Exactly one auth method must be set — a password or a key, never both and never neither. An ambiguous pair is a validation error rather than a silent preference, because which one labops picked would only become visible when a connection failed.

Key	Type	Default	Description
username	string	required	The SSH user labops connects as.
password	string	unset	Password authentication. Mutually exclusive with ssh_key_path. Note that some operations only work with a key, so labops warns when this is the only method available.
ssh_key_path	path to a file	unset	Path to a private key. ~ is expanded. Mutually exclusive with password. The file must exist, so a typo fails at labops validate rather than at connection time.

Selector

Which nodes a command acts on. Every field empty means "no constraint".

AND across fields, OR within a field::

kind: [lxc], os: [debian]  ->  debian containers
tags: [prod, edge]         ->  tagged prod OR edge

A Pydantic model rather than a parsed string because it has two front doors that must agree: the labops update CLI options, and the reusable named sets under settings.targets. One model means one matcher, one set of error messages, and no grammar to keep in sync.

Key	Type	Default	Description
kind	list of host | vm | lxc	empty	Node classes to include: host, vm, lxc — the node's place in the tree. A single value may be written unquoted instead of as a list.
os	list of debian | alpine | redhat | unmanaged	empty	Operating systems to include: debian, alpine, redhat, unmanaged.
tags	list of string	empty	Match nodes carrying any of these tags. Tags are local to the node that declares them and are not inherited, so use under to sweep a subtree.
under	list of string	empty	Node names. Matches each named node and everything below it, so this is how you select a whole Proxmox host with its guests. An unknown name is an error rather than an empty selection, which would look like a successful no-op.
exclude	list of string	empty	Node names to exclude. Each named node and everything below it is removed after the positive filters have run. An unknown name is an error, same as under.