Frequently asked questions

A self-hosted, open-source monitor for a small fleet, from one host to about a hundred. It answers four questions: are the systems healthy, are the apps answering, did the backups succeed (checked at the destination), and did the scheduled jobs check in. It sends alerts to webhooks and email, and has a REST API, a live event stream, an MCP server and a CLI. See the project README.

Yarrix is preparing its first release. The features in the docs are built and covered by tests, except where a page says otherwise; restore tests for backups are the main example. Not every platform has been run on real hardware yet, and the platform table says which have. Until 1.0, only the latest release and the main branch get fixes (security policy).

Yarrix is open source under the Apache License 2.0. Nothing in it needs an account with anyone: the hub runs on a machine you own and keeps its configuration and data there. The first person to open a new hub creates the admin account on that hub (auth.md).

No. This site is information only and Yarrix never contacts it. The hub's only outbound connections are the ones you configure: alert destinations, checks, SSH, and the agents' own connection to your hub. It doesn't check for updates either; you decide when to upgrade (security.md).

Either Docker with the Compose plugin, or the hub as a single executable with the web app inside (no Bun needed), for Linux x64 and arm64, macOS x64 and arm64, or Windows x64. The container image is built for linux/amd64 and linux/arm64 and runs as a non-root user. Both ways listen on 127.0.0.1:7790 only until you change it, so a new hub is never exposed by accident. The quickstart gets you from nothing to a first alert in about ten minutes; install.md lists every file.

Linux, Unraid, UGREEN UGOS Pro, Synology DSM 7.2+, macOS and Windows, each with the agent or agentless over SSH. So far: Linux is exercised end to end in containers by the test suite; agentless monitoring has run on real Unraid 7.2.2; agentless and the systemd agent have run on a real UGOS NAS. Synology, macOS and Windows have not yet been run on real hardware. Their code and docs follow the vendor's documentation and are covered by tests. The platform table is kept current, and each platform page says what has been exercised.

No. Each host is read one of three ways, and you choose per host. The agent is one small binary or container that connects out to the hub; it reads the most and keeps samples on disk while the hub is away. Agentless installs nothing: the hub signs in over SSH and reads the host with a probe script. A relay is an agent on a neighbouring machine that reads hosts the hub cannot reach. See collection methods.

Neither, for the basics. The agent connects out to the hub, so the host needs no inbound port, and CPU, memory, disks, network, load and uptime need no root. Some readings do need more access, SMART disk health for example; without it they show as unknown with the reason rather than as a fake value (AGENT.md, Linux).

There are recipes for Unraid (a container template), Synology DSM 7.2+ (a Container Manager project) and UGOS Pro (a Compose project). They are written from each vendor's documentation; what has been run on real hardware is in the platform table. See NAS recipes.

Open Add a host in the web app, name the host and pick its platform. For an agent, the wizard shows that platform's install commands with a one-time enrollment token filled in, or, on Linux with systemd and macOS with launchd, it can install it for you over SSH. For agentless, it makes an SSH key for that host alone and tests the connection before anything is saved. An agent on the same network as the hub can also find it by itself and join with a PIN. See the quickstart.

You choose per host: notify shows that an update exists, one_click (the default) adds an Update button, and automatic updates on its own, inside a time window if you set one, one canary host first, and stops if two hosts fail on the same release. The hub only ever sends a version number. The agent fetches the files from your own hub and installs them only if they carry a valid signature from a key it already trusts, and a new build that crashes or can't reach the hub rolls back by itself. Containers are updated by pulling a new image. Self-update on Windows has not yet run on a real Windows machine. See Updating the agent.

Back up the database and config folder, read the release notes, then replace the image or the executable. Database changes run when the new version starts, each in its own transaction, so a failed one leaves your data as it was. Going back to an older version means restoring the copy you took first. See Upgrading, backing up and restoring the hub.

No. It watches the jobs you already run, such as rsync, restic, borg or Time Machine, and checks the result at the destination instead of taking the job's word for it: is the copy fresh, a plausible size, intact, and is there room for the next one. See backups.md.

Not yet. Restore tests are planned for a later release, and until then check B9 always reads skip. A backup Yarrix calls healthy has been seen to run, to finish and to look right at the destination; it has not been proven restorable, so test a restore yourself now and then (backups.md).

It says so rather than guessing. A reading that exists but can't be taken this way is unknown, and one that doesn't exist on that platform is n/a, each with the reason, and never shown as zero. An unknown never sets a host's state, and an unknown backup check stops the run from counting as a success. A laptop that goes to sleep shows as asleep, with when it was last seen, not as down (platforms.md, backups.md).

Give it a heartbeat. The job pings its own address when it runs, and also on start, failure or with its exit code if you like; if a ping doesn't arrive on time, you get an alert. Or wrap the command in yarrix run, which reports the start, the exit code and the last 10 KB of output. If the hub is unreachable, the job runs as usual. The ping address is a credential, so treat it like a password (heartbeats.md).

To webhooks in Slack, Discord or ntfy format, Yarrix's own JSON or a template you write, and to email. Rules decide what goes where, and an alert no rule picks up still goes to the default destination. Quiet hours hold the severities you choose and send one summary when they end, and there is a daily digest. Every alert is queued in the database before it is sent and retried if it fails, and webhooks can be signed so the receiver can tell they came from your hub (alert routing, alert delivery).

Yes. A custom check is a command you choose, run on a schedule, whose output becomes a status: a ZFS pool, a vendor tool, a local API. The hub runs it over SSH with the host's own account, or an agent runs a command you named in that machine's own agent.yaml; the hub can name such a command but cannot send one (custom checks).

A monitor can reach every machine it watches, so Yarrix keeps that reach narrow. The hub listens only on the machine it runs on until you open it up, and it never phones home. Agents never run a command the hub sends. Each agentless host gets its own SSH key, and SSH passwords typed into the setup wizard are used once and never stored. Releases are signed, and agents install only signed updates. The security hardening guide lists what to do before you point it at anything you care about.

With a username and password kept on the hub (on by default), through Supabase with OAuth, or by Tailscale identity, plus a recovery login link for when you are locked out. Passwords are checked with OPAQUE, so the hub never receives the password itself. People get one of three roles: viewer, operator or admin. Until the first admin exists, anyone who can reach the hub can claim it, so do that straight away (auth.md).

On your own network plain HTTP works, but it is not encrypted, and the web app shows a "Not encrypted" banner when opened that way from another machine. For anything beyond your own network, put the hub behind HTTPS, with a reverse proxy or tailscale serve, and set YARRIX_PUBLIC_URL. The web terminal needs HTTPS or localhost either way (auth.md).

There is, and it is off until you set it up on purpose: it must be switched on in the config and given a target on each host, and the docs walk you through giving it its own SSH key and account. Only a browser session that signed in within the last 12 hours can open one, a viewer never can, and an operator only for the hosts their rule lists. Sessions are audited, and output can be recorded (terminal.md).

Each release has a SHA256SUMS file signed with minisign, and the project's public key is in the repository. Check the signature first, then the checksums (verify-release.md). Separately, the macOS binaries are not notarized and the Windows installer is not Authenticode-signed yet, so Gatekeeper and SmartScreen will warn; the macOS and Windows pages say what to expect.

Privately, please, not in a public issue. Use GitHub's private vulnerability reporting on the repository (Security tab, "Report a vulnerability"), or write to security@yarrix.io if that isn't available to you. Details are in the security policy.

Yes. Everything the web app does is in a REST API with an OpenAPI description, and tokens carry a scope: read, report or admin. There is a live event stream, a read-only MCP server for assistants, and a read-only CLI whose yarrix status exits 0, 1 or 2 for ok, warn or critical (REST API, MCP and CLI).

The hub is Bun and TypeScript with SQLite, the web app is React, and the agent and CLI are one Rust binary. The design decisions, and what was considered and rejected, are in DECISIONS.md.

Read CONTRIBUTING.md first. Commits use conventional messages with a Signed-off-by line certifying the Developer Certificate of Origin (git commit -s), and the commit hook checks it once installed (bun run hooks:install).