Yarrix
GitHub

Documentation

Everything about installing, running and securing Yarrix. These pages are built from the docs folder of the repository, so they describe the same code. New here? Start with the quickstart.

Get going

  • QuickstartAbout ten minutes, from nothing to a monitored host and an alert you have seen arrive. Pick one hub path (Docker or a single binary), then do the…
  • InstallYarrix is self-hosted only. The hub is one container image or one executable; the agent is one static binary (or a small container). Nothing here…

Everyday tasks

  • WorkflowsShort guides to the everyday tasks, with links to the pages that cover each one in detail.

Configuration

  • ConfigurationYarrix 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…
  • Configuration referenceEvery field Yarrix reads from its config folder, one row per field. For how the files fit together, secrets, layering and validation, read…

How hosts are read

  • Collection methodsA host is read in one of three ways. You choose per host with collect.method in hosts/<id>.yaml.
  • Host agentThe token is exchanged on first connect for a per-host token kept in the state directory (state.json, mode 0600). After that the enrollment token is…
  • PlatformsSix platforms are supported, and every one of them can be monitored with the agent or agentless over SSH. The agent reads more and keeps reading…

Per platform

  • LinuxAny distribution on x86_64, aarch64 or armv7. What each method reads is in the platform table.
  • Unraidx86_64 only. Unraid runs its root file system from RAM; only the flash drive (/boot) and the array persist. What each method reads is in the platform…
  • Synology DSMDSM 7.x on x86_64 and aarch64. What each method reads is in the platform table.
  • UGREEN UGOS ProUGOS Pro is Debian-based with systemd, Docker, and root SSH. x86_64 and aarch64 models. What each method reads is in the platform table.
  • macOSApple Silicon and Intel. What each method reads is in the platform table.
  • WindowsThe Windows agent and the Windows probe have never run on a real Windows machine. They are cross-compiled, linted and unit-tested against…

Status pages and badges for people outside Yarrix

  • Status pages and badgesA status page is a read-only page that answers "is it working?" for people who do not use Yarrix: a team, customers, a wall display. A badge is a…

Services, jobs and backups

  • App checksAn app check answers "is the service answering?". The hub (or an agent you name) calls the service on a schedule and the result shows on the Apps…
  • Heartbeats and yarrix runA heartbeat answers "did the job run?". Instead of Yarrix looking at the job, the job tells Yarrix. If a ping does not arrive on schedule, Yarrix…
  • BackupsYarrix does not take backups. It watches the jobs you already have and, where it can, checks the result at the destination instead of trusting the…
  • Custom checksA custom check is a command you choose, run on a host on a schedule, whose result becomes a status in Yarrix. Use one when none of the built-in…

Alerts

  • Alert routingAlerts are set up in alerts.yaml. Three ideas: destinations (where a message can go), rules (which alerts go to which destinations), and behavior…
  • Alert deliveryHow Yarrix sends an alert once routing has chosen a destination. Routing itself (rules, quiet hours, silences) is in alerts.yaml; this page is about…

Sign-in and safety

  • AuthenticationProviders prove who someone is. The core decides what they may do. Nothing is open by default: until a first admin exists, every route except /setup…
  • Web terminalA terminal is a real shell on a host, opened from the browser, so set it up on purpose. It is off until you do all of this.
  • Security hardeningYarrix can reach every machine it monitors, and with the terminal on it can open a shell on them. Read this page before you point it at anything you…

Running it

  • Upgrade, back up, restoreThis page covers the hub: what to keep, how to move to a new release, and how to get back if something goes wrong. How agents move to a new release…
  • Verifying a releaseA release carries checksums and a signature so you can tell that what you downloaded is what the maintainers published. Check before you run…

Automation

  • REST API, MCP and CLIEverything the web app does goes through the REST API under /api/v1, and you can use it too. The machine-readable description is OpenAPI 3: the hub…

More

  • Hub on a Mac (launchd)For a Mac that should run the hub all the time. It builds the single-file hub executable (web UI inside), installs it under one folder, runs it as a…

Working on Yarrix

  • Project READMEWebsite and project information: https://yarrix.io (information only; Yarrix itself never contacts it).
  • DecisionsArchitecture decisions for Yarrix, with the alternative each one rejected.
  • ReleasingReleases are built, signed and published from a maintainer's own machine. No GitHub runner builds or signs anything. One command does it:
  • Terminal PTY notesVerdict: GO on Bun.Terminal. The node-pty fallback is not needed. All four checks pass on the pinned runtime, with the caveats under "What this does…