Agent settings#

Administration → Agent settings is the agent's own policy, not the router's. Four values, stored in the agent's state file, applied without a restart. It is admin-only: the page is behind an admin-gated navigation entry and both endpoints are adminOnly.

Nothing on this page stages. There is one Save changes button, which is disabled until something differs from what was loaded and reads Saved when nothing does.

GET /api/admin/settings loads them; PUT /api/admin/settings saves them and writes an update-settings entry to the audit log.

The four settings#

Setting	JSON field	Default	Accepted range
Session lifetime (minutes)	`session_ttl_minutes`	720	5 to 43 200
Require two-factor for every account	`require_totp`	off	—
Commit-confirm window (minutes)	`commit_confirm_minutes`	2	1 to 60
Audit entries retained	`audit_retention`	2000	anything below 100 is raised to 100

Out-of-range values are refused with a 400 that names the rule — "session TTL must be between 5 minutes and 30 days", "commit-confirm window must be between 1 and 60 minutes" — agent/admin.go, handleUpdateSettings.

Session lifetime#

How long a browser stays signed in. The form's hint explains the default: "720 is twelve hours — a working day plus slack."

Require two-factor for every account#

Commit-confirm window#

The default number of minutes offered when a commit arms commit-confirm. Short enough to matter, long enough to notice — those are the form's own words, and the trade is real: if you do not confirm within the window, the router reboots into the previous configuration.

Audit entries retained#

How many entries the agent keeps in memory to serve GET /api/audit. It is not a retention policy for the file: the file is append-only, rotates at 8 MB and keeps one previous generation, and entries beyond this number stay in it and are readable on the box.

The number is also capped at 10 000 whatever you set, and the agent logs a warning saying so — a number the settings page echoes back and the agent does not honour is worse than a refusal. The hint says where the real answer is: "Kept in the agent's state file. Ship them off-box for real retention."

The licence key is not shown here#

The licence key is stored in the same settings structure, and handleGetSettings blanks it before answering — the Licence page shows the licence, not its key. A settings save also carries the stored key forward explicitly, so saving this page can never drop the licence.

Start-up settings, which are not on this page#

The last panel says so:

The TLS certificate, the address the console listens on, the router API endpoint, fleet mode and the licence-key file are start-up settings, not policy: they are arguments on the wheelhouse-agent service and take effect when the agent restarts. Changing them needs console or SSH access to this box; the notes are in /usr/share/doc/wheelhouse-agent/.

The shipped unit passes these — packaging/wheelhouse-agent.service:

--api-url https://127.0.0.1
--api-key-file /config/wheelhouse/api-key
--admin-token-file /config/wheelhouse/admin-token
--license-key-file /config/wheelhouse/license-key
--addr 0.0.0.0:8443
--tls-self-signed
--ui-dir /usr/share/wheelhouse/ui
--data-dir /config/wheelhouse
--log-level info

The data directory is /config/wheelhouse because /config is the persistent partition: the state file, the audit log, the self-signed key and the licence survive an image upgrade there, and would not under /var/lib.

Other flags worth knowing exist but are not set by the shipped unit — among them --metrics-public (serve /metrics unauthenticated), --trust-proxy (honour X-Forwarded-For, only behind a reverse proxy you control), --fleet-config, --reconcile-file, and the single sign-on flags. The full list is in registerFlags() in agent/main.go.

From the API#

bash

curl -sk -H "Authorization: Bearer $T" https://<router>:8443/api/admin/settings

json

{
  "session_ttl_minutes": 720,
  "require_totp": false,
  "audit_retention": 2000,
  "commit_confirm_minutes": 2
}

A PUT takes the same object. It replaces all four values, so send the whole structure rather than one field.

What this page will not do#

It does not configure the router. Everything about the box itself is on System → Settings.
It does not manage accounts. Users, roles, tokens and your own two-factor are on the Users, API tokens and Account pages.
It cannot change a start-up flag. Those need console or SSH access and an agent restart.
There is no per-object permission model behind it. Three roles, enforced per route, is what exists.