The desired-state file#

One file says what the router's configuration should look like; the agent reads the live configuration, works out the set and delete commands that close the gap, and hands them to the same staging area everything typed into the web UI goes through. The file mirrors the router's configuration tree. There is no Wheelhouse-specific schema: if you can write the node path in set, you can write it here as nesting.

service:
  dns:
    forwarding:
      cache-size: 10000
  ssh:
qos:
  interface:
    eth1:
      egress: WAN-OUT

$ wheelhouse-agent plan --file /config/wheelhouse/agent.yaml
set service dns forwarding cache-size 10000
set service ssh
warning: service.ssh: planned as a bare set (a node with no value)

2 change(s) needed in /config/wheelhouse/agent.yaml

Where the file lives#

agent.yaml is a convention, not a format promise — the parser sniffs the content, so a .yaml file holding JSON works and a mislabelled file fails on its contents rather than silently parsing into the wrong shape.

The API route is deliberately narrow: the name must end .yaml, .yml or .json, must not begin state., and must resolve inside the data directory — no separators, no .., and an absolute path only if it lands in the data directory anyway. Without those rules the endpoint would render state.json — accounts, password hashes, TOTP secrets and raw session ids — as a diff of set operations for anyone who could sign in.

Format sniffing#

The YAML path decodes through the node tree rather than into a Go map, so the text in the file is the value. That matters more than it sounds:

The router stores text. Anything that retypes a value on the way in produces a diff that never converges.

A key with no value#

A mapping key with nothing after the colon (ssh: in YAML, {} in JSON) means this node exists — the shape the configuration tree uses for a node that is switched on rather than set to something. What it does depends on what the router holds there, so the engine decides against live state:

That last one is the case no operation can express: the router cannot set a node that requires a value to nothing, so the file is broken rather than the router being wrong.

An explicit empty string is a different thing and is refused earlier, where the document is read, before any diffing:

service.dns.forwarding.cache-size: an empty value is not something VyOS can set — give
it a value, or drop the key (a key with nothing after the colon switches a node on)

The check walks the whole document, so a blank in a subtree the diff never reaches is still reported, and the message names the file rather than the router.

Multi-valued leaves#

A node that holds several values — name-server, address, allow-from — is written as a list and diffed value by value:

system:
  name-server:
    - 192.0.2.53
    - 198.51.100.53

Each missing value becomes its own set system name-server <value>; in full mode each extra live value becomes its own delete. A single value may be written bare rather than as a one-element list; the router reads back a single-valued node as a string and a multi-valued one as an array, and both shapes compare the same way.

An empty element anywhere in a list is refused with the same message as an empty scalar.

Partial and full#

How a value is compared#

Every value in the configuration tree is text. A document may spell the same thing typed — YAML cache-size: 10000, JSON true — while the router answers "10000". Both sides are canonicalised to their string form before comparison, so a typed document does not produce a plan that re-sets what the router already satisfies and never converges.

Warnings#

Warnings are advisory, never refusals: the operations they accompany are still what would change.

They come back in the warnings field of POST /api/reconcile and GET /api/reconcile/file, on stderr from plan, and the reconcile loop logs a set of warnings once per change rather than once per pass, so a steady file stays quiet.

Reading against the router, not the cache#

The diff always reads the router's configuration uncached. The agent's read cache is invalidated by the agent's own commits, so a change somebody made over SSH — the thing drift detection exists to notice — would otherwise stay invisible for up to an hour.

plan exit codes#

Exit 2 is the diff -q convention, so plan drops into a shell test or a CI gate without parsing text:

if ! wheelhouse-agent plan --file /config/wheelhouse/agent.yaml >/dev/null; then
  echo "router has drifted"
fi

--json gives a machine-readable document instead of lines:

{
  "file": "/config/wheelhouse/agent.yaml",
  "full": false,
  "ops": [{"op": "set", "path": ["service", "dns", "forwarding", "cache-size", "10000"]}],
  "count": 1,
  "warnings": []
}

Note the shape of an operation: for a set, the last path element is the value. That is the router's own /configure convention, and it is why a path element may never be empty.

The four surfaces, and what each may do#

The reconcile loop#

Off unless --reconcile-file is set. One pass is: read the file, read the router, diff, then either stage the difference or commit it.

In commit mode with a confirm window, the loop commits, then re-reads the configuration. If the router still answers, the change did not cut the agent off, so it confirms — the way an operator does when the page still loads. If the router has stopped answering it does not confirm and says so, leaving the router to roll back on its own timer.

State is readable at GET /api/drift:

{"managed":true,"file":"/config/wheelhouse/agent.yaml","mode":"stage",
 "drifted":true,"ops":2,"checked_at":"2026-09-02T22:27:07Z"}

mode:"off" means no file is being managed. The three wheelhouse_desired_* metrics are absent entirely in that case.

See also#

• wheelhouse-agent — plan and apply.
• Every flag — the six --reconcile-* flags.
• Endpoint index — /api/reconcile, /api/reconcile/file, /api/drift.
• Exit codes
• Prometheus metrics — the drift gauges.
• Audit entries — what the loop records.
• Desired state — the idea, and what it costs.
• State against intent

Checked against#

agent/desired.go (parseDesiredDoc, decodeYAMLTree, yamlValue, validateBlank, loadDesiredFile, reconciler, runPlanApply, printOps), agent/reconcile.go (reconcile, flattenDesired, multiLeafOps, sameLeaf, currentConfig, handleReconcile, handleReconcileFile, allowedDesiredName, resolveDesiredFile, emptyValueHint), agent/desired_test.go, docs/deploy.md "Desired state", docs/adr/001-desired-state-file.md, PLAN.md §6.