The commands Wheelhouse runs#

The agent is a separate program that drives the router over its documented HTTP API. It does not link against the router's code, and it does not shell out. Everything it knows comes from the reads on this page, and everything it changes goes through /configure.

This is the whole list.

The router API endpoints it posts to#

Three timeout tiers. A read that hangs must not hold a dashboard; a commit on slow hardware can run past fifteen seconds, and timing out mid-commit leaves the caller unable to tell whether it landed; an image pull is bounded by the uplink, and the router keeps pulling after the agent hangs up.

Two encodings, set by the router's own parser: most calls are form-encoded, but its form parser requires a path field on every command, so operations that have none (confirm) and fields it does not read (confirm_time) go as JSON instead.

Operational reads#

Every one of these is show <path> through /show. This is the complete list; nothing else is read.

Re-derive it:

grep -ohE 'showText\([^,]*, [^)]*\)' agent/*.go | sort -u

Configuration subtrees it reads#

Through /retrieve with showConfig. The whole tree (an empty path) is read too — by the reconcile diff, and by the Config tree page.

container                     protocols               service dhcp-server
container name                protocols bgp           service dns
container network             protocols ospf          service dns dynamic
firewall                      protocols static        service lldp
firewall group                qos                     service ntp
firewall ipv4                 system                  service suricata
high-availability             pki                     service conntrack-sync
interfaces                    policy                  vpn ipsec
interfaces openvpn            load-balancing          nat
interfaces wireguard          service                 service router-advert
vrf

Re-derive it:

grep -ohE 'configOf\(vyos, [^)]*\)|configTag\(vyos, [^)]*\)' agent/*.go | sort -u

What it writes#

Only through /configure, and only as set and delete operations whose path the operator has seen. The staging endpoint refuses anything else:

[{"op":"set","path":["service","dns","forwarding","cache-size","10000"]},
 {"op":"delete","path":["nat","destination","rule","10"]}]

For a set, the last path element is the value — the router's own convention, and why an empty path element is refused where the request can still say which operation is wrong.

Commit-confirm is the router's native mechanism: confirm_time on the commit, and a later confirm operation to cancel it. Miss the window and the router reboots, and starts with its saved configuration: what save last wrote, not the configuration from before the commit. That reboot is the rollback.

Rollback is not an operation at all. The router's HTTP API has no rollback; the CLI command works by loading the archived configuration file for that revision, so POST /api/rollback loads /config/archive/config.boot.<N>.gz through /config-file and commits it.

What it costs the router#

Every call into the router's HTTP API forks a shell helper on the router, so the agent budgets calls, not intervals.

Idle, that is roughly a dozen calls a minute.

The router serialises its HTTP API: concurrent reads are no faster than sequential, and each read is in the region of 150 to 800 milliseconds. The primer does not stagger its calls, and it does not refresh operational reads on a timer.

Reads that bypass the cache#

GET /api/apps/plan also reads show container image uncached: it is asked right after a pull, and the three-second cache would answer with the list from before it.

Two cautions#

See also#

• Which page writes which subtree
• Endpoint index — the agent endpoint each read is behind.
• Prometheus metrics — wheelhouse_vyos_* and the cache counters.
• The desired-state file — the uncached diff.
• Ports and listeners — where the router's API listens.
• The agent and the router
• Advanced mode and the router's commands
• Built on VyOS