Configuration

Yarrix is configured by plain YAML files in one folder, so you can keep them in git. The hub watches the folder and reloads a file when it changes. Every field of every file is in the generated config reference; this page explains how the pieces fit.

Where things live#

The Docker image mounts them at /config and /data. The other YARRIX_* variables (listen address, public URL, base path, log format) are in the README.

An empty config folder gets a commented starter yarrix.yaml on first run; an existing file is never overwritten.

The files#

Every file is optional except that something has to tell the hub what to monitor: enrolling an agent is enough to see a host. Fictional examples of every file are in examples/config/.

yarrix.yaml must start with version: 1; the first-run starter file already does. Without it the whole file is refused (and so are settings in it such as self_monitor.ping_url) with an error that names the missing line.

A host's id (lowercase letters, digits, -, _; at most 64 characters) is the file name without .yaml.

Rules the loader follows#

• Unknown keys are errors, so a typo fails loudly instead of being ignored. The error carries file:line:col.
• A file that fails to load keeps its last good version active, and the error is listed at GET /api/v1/config/errors. One bad host file never stops the rest.
• Layering. A host's effective settings are, from weakest to strongest: built-in defaults, defaults.yaml, the host file, then a single check's own fields. GET /api/v1/config/effective/{kind}/{id} shows the merged result.

Secrets#

Anywhere a field is marked secret (tokens, passwords, webhook URLs, signing keys), write a reference, not the value:

password: ${env:SMTP_PASSWORD}          # an environment variable of the hub process
token: ${file:/run/secrets/atlas_token} # the contents of a file, one trailing newline removed
url: ${secret:slack-hook}               # a value typed in the web app, kept encrypted by the hub

A secret saved from the web app or the config API must be one of these references; the hub refuses a plain value. How the encrypted store, its keys and the recovery key work is in security.md.

A value read this way never appears in API responses or logs. A plain-text secret still loads but produces a warning. A reference that cannot be resolved invalidates only the object that uses it; the rest of the file loads.

Under Docker, ${env:NAME} only works if the variable is passed into the container (add it to environment: in your compose file). ${file:...} paths are paths inside the container.

Checking a folder before you rely on it#

yarrix-hub config check                  # validates the whole folder, exit 1 on any error
yarrix-hub config check --config-dir DIR

It resolves secret references, so run it with the same environment as the hub (a missing ${env:...} is reported as an error, as the hub would).

JSON Schemas for every file are in proto/config/ for editor completion: point your editor's YAML support at them. bun run schemas:export regenerates them; bun run docs:generate regenerates them and this folder's config-reference.md and platforms.md. A test fails if the documents are out of date.

Changing config at runtime#

PUT /api/v1/config/files/{path} (admin) writes the same files, keep comments and order, and make one local git commit when the folder is a git repository (never pushed). Changing a command-bearing field needs an admin signed in to the web app, not an API token (security.md).

The Network page#

Config → Network sets two things, both saved in yarrix.yaml under network. Each change is applied at once, and the page says what it will do before you commit.

• Port (network.port, default 7790). The hub opens the new port first and saves the change only once it is listening. If the port is taken, the hub stays where it is and says so. The old port keeps answering until the hub restarts, for agents that are away; connected agents move to the new port on their own, and the page counts how many have. If the page reached the hub on the old port directly, it reopens on the new one; through a proxy it stays put, so repoint the proxy first. YARRIX_PUBLIC_URL should name the new port as well, before the hub restarts.
• Allow other computers on my network (the LAN switch, network.lan, default off). Off, the hub listens on this computer only. On, it listens on all interfaces, so agents and browsers on other computers can reach it, and it advertises itself on the local network so a new agent can find it without an address. Turning it off asks first when it would cut off this browser or connected agents. If the hub cannot open the new listener, the page says so and the log records network.lan_failed with the reason.

When other computers reach the hub over plain HTTP, the page says the traffic is not encrypted. See Plain HTTP and HTTPS.

YARRIX_LISTEN in the deployment fixes the port and the LAN switch. The page then shows them as Set by the deployment and cannot change them: change the setting where the hub is deployed instead (for Docker, the published port in the compose file). YARRIX_DISCOVERY=off stops the local-network advertisement; new agents can still join with the hub's address and a PIN.

Disabling and deleting#

Set enabled: false on a host (its file), or on one app, custom check, backup or heartbeat, to switch it off without losing anything. A disabled host or check is not collected, polled or alerted on; an incident that was open resolves at the next alert tick; its history stays and can be read, and it shows as Disabled rather than down or unknown. A disabled host switches off everything under it. Remove the line (or set true) and it resumes; a backup or heartbeat gets a fresh grace period instead of reporting the time it was off as late. The Config screen has a switch for each, and it writes the same field. Reports to a disabled backup are accepted and ignored; heartbeat pings are still logged.

Nothing is deleted automatically. If you delete a host file, the host appears in Config under Removed from config with its data kept, until an admin deletes it. Deleting is DELETE /api/v1/hosts/{id}?confirm={id} (admin signed in to the web app, audited as host.deleted). It removes the host's data and, when the host is still in config, its hosts/<id>.yaml, but only if the host is disabled first and no check file still refers to it.