Install

Yarrix 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 phones home.

Verify a download before running it: sha256sum -c SHA256SUMS --ignore-missing, and check the minisign signature on SHA256SUMS (verify-release.md).

What the install commands check. The Linux and macOS install commands (the ones the wizard shows, and the ones the hub runs over SSH) check each agent file against the release's signed MANIFEST.json. The hub checks that signature itself, against the built-in release key (the one the agent trusts); set YARRIX_RELEASE_PUBKEYS on the hub only to replace that key, for a build you signed yourself. When the signature verifies, the commands carry each file's hash from the manifest, and the install stops, and removes the download, if the file does not match or if the binary does not report the manifest's version. This needs no minisign on the machine, and no YARRIX_SKIP_SIGNATURE_CHECK. When the signature does not verify, the commands check the manifest's signature with minisign on the machine (brew install minisign, apt install minisign) and never fall back to the .sha256 alone: the install stops, and removes the download, if minisign is missing, the signature does not verify, the manifest is for another version than the hub's, or the file is not listed in it. To install anyway on such a machine, set YARRIX_SKIP_SIGNATURE_CHECK=1 (for example sudo env YARRIX_SKIP_SIGNATURE_CHECK=1 sh): it then checks only the .sha256 and prints a warning. A hub that serves no signed manifest is checked by the .sha256 alone, which comes from the same server as the file, so it catches damage, not a swapped file. The release page (HTTPS to GitHub) checks the signature when minisign is installed and otherwise falls back to the .sha256. The Windows script (install-agent.ps1) checks the -Sha256 you give it or the published .sha256, and does not check the signature. The UGOS, Synology and Unraid steps check the .sha256 only. For those, or whenever the file matters, check the signature by hand as above. To move an existing hub to a new release, and to back it up, see upgrade-backup-restore.md.

The hub with Docker Compose#

mkdir yarrix && cd yarrix
curl -fsSLO https://raw.githubusercontent.com/yarrix/yarrix/main/deploy/docker/compose.yaml
mkdir config data
printf 'YARRIX_UID=%s\nYARRIX_GID=%s\n' "$(id -u)" "$(id -g)" > .env   # so the non-root container can write ./config and ./data
docker compose up -d
docker compose logs hub | grep "First run"     # the one-time link that creates the admin

The first start writes a commented yarrix.yaml into ./config and prints the first-run setup address. Open it right away: whoever gets there first (within the first hour) sets the admin password. The hub is published on 127.0.0.1:7790 only. To reach it from other machines, put an HTTPS reverse proxy in front, set YARRIX_PUBLIC_URL to its address and read auth.md. Sign-in works over plain HTTP on your network, but the connection is not encrypted, so use HTTPS for anything beyond it. The web terminal needs HTTPS: Docker's port publishing makes every request arrive from the bridge gateway rather than loopback, so the hub does not treat a plain-http 127.0.0.1:7790 visit as local and refuses the terminal. Put the hub behind TLS, or set YARRIX_PUBLIC_URL to an https:// address (terminal.md). YARRIX_PORT changes the published port. The container has a read-only root file system, no capabilities and a health check (yarrix-hub healthcheck). The image includes an OpenSSH client for agentless hosts and the web terminal; mount your SSH keys read-only and read security.md for the file rules.

On Docker Desktop for Mac, a folder bind-mounted at ./data can hide database changes made by a second process from the running hub: a token made with docker compose exec hub yarrix-hub auth token create may be refused (401) by the hub that is running, and works after a restart. Use a named volume for /data there (- hub-data:/data, with a top-level volumes: { hub-data: }); Linux hosts are not affected, and the config folder can stay a bind mount.

Build the image yourself instead: docker compose up -d --build from a checkout, or docker build -f deploy/docker/Dockerfile.hub -t yarrix ..

The hub as a plain executable#

chmod +x yarrix-hub-linux-x64
YARRIX_CONFIG_DIR=/etc/yarrix YARRIX_DATA_DIR=/var/lib/yarrix ./yarrix-hub-linux-x64

It reads the same YARRIX_* variables as the image. Build one with bun scripts/build-hub-binary.ts.

Agents#

The quickest way is the web app: a hub with no hosts opens on Add your first host (later, Config → Add a host). It writes the host file, mints a one-time token and prints that platform's install commands with the token and the hub's address filled in, then waits for the agent's first report. For an agentless host it makes a key for that host alone (at $YARRIX_DATA_DIR/ssh/keys/<host name>; the host's file points at it), shows its public half to authorise, can install it for you with the host's password (typed once, never stored: security.md), and has a Test connection that runs one probe before saving. Set YARRIX_PUBLIC_URL so the commands carry the address agents reach, not the one your browser used.

Install it for me. In the wizard, choose the agent method and then Install it for me (Linux with systemd, or macOS with launchd; Auto and Other platforms are tried and the host says what it is). The hub signs in over SSH, works out the OS and CPU, downloads the right build (from its own /download/agent when YARRIX_AGENT_DIST holds the whole set, otherwise from the GitHub release), checks its checksum, writes the settings and a one-time token, starts the service, and the wizard waits for the first report. Root is handled openly: the login either is root, or uses sudo with the password you typed (used in memory for that one run), or fails with "needs root" and the commands to run yourself. Passwords are never stored. Not automated, with the commands shown instead: Unraid, Synology, UGOS and Windows. The manual commands stay available on every host, including after a failed automatic install. The same flow can reinstall an agent that is already enrolled but too old to update itself (or whose self-updates keep failing): the host drawer offers it, it keeps the host's enrollment and settings, and mints no new token. See AGENT.md. See security.md.

With a PIN. The wizard also makes a six-digit PIN for the host. On Linux or macOS, download the agent from the hub (or the release) and run sudo ./yarrix agent join: it finds the hub on the network, asks for the PIN, writes the settings and installs the service. On Windows, run the installer and type the PIN. In a container, set YARRIX_SETUP_PIN. There is no address to type unless the hub is on another network, when the agent asks for it. See AGENT.md.

By hand: mint a token on the hub (docker compose exec hub yarrix-hub enroll create --host nas-1), then install the agent (AGENT.md). The hub serves the agent files it was given from YARRIX_AGENT_DIST at /download/agent/<file> (the image ships the release set), for example:

curl -fsSLO https://yarrix.example.net/download/agent/yarrix-linux-x64-musl
curl -fsSLO https://yarrix.example.net/download/agent/yarrix-linux-x64-musl.sha256
sha256sum -c yarrix-linux-x64-musl.sha256

The Windows installer is at /download/agent/yarrix-agent-setup-windows-x64.exe and the zip at /download/agent/yarrix-windows-x64.zip; see the Windows page.

The agent in a container#

With the PIN from Add a host (the agent finds the hub itself and joins once; network_mode: host is what lets it see the hub):

YARRIX_SETUP_PIN=458-283 docker compose -f deploy/docker/compose.agent.yaml up -d

Set YARRIX_HUB too if the hub is on another network. With a token instead:

YARRIX_HUB=https://yarrix.example.net YARRIX_ENROLL_TOKEN=<token> \
  docker compose -f deploy/docker/compose.agent.yaml up -d

The flags that matter (all in that file): --pid=host and --network=host so processes and network interfaces are the host's, a /state volume for the per-host token, and read-only mounts of the disks to report. Container inventory needs the Docker socket, which is off by default because it gives whoever holds it root on the host (security.md). If the hub is plain http:// (a LAN test, say), set YARRIX_INSECURE=1 in the agent's environment: the compose file passes it through (YARRIX_INSECURE: ${YARRIX_INSECURE:-}), so put YARRIX_INSECURE=1 in the .env beside it, or prefix the docker compose command with it. A native binary takes --insecure instead. The agent refuses a non-HTTPS hub otherwise. The image carries smartctl, but reading SMART needs extra privileges that the default container lacks; the compose file lists the options. The image is about 3 MB (amd64) to 7 MB (arm64).

NAS recipes#

These recipes are written from each vendor's documentation and have not been run on real Unraid, Synology or UGOS hardware.

Releasing (maintainers)#

Releases are cut from a maintainer's own machine with scripts/release/cut.sh <version>: it checks, builds and packages every artifact above, signs them, tags and creates a draft GitHub release. scripts/release/dry-run.sh [version] does the builds alone into dist/release/<version>/. See RELEASING.md. THIRD_PARTY_NOTICES.md is generated: after a dependency change, run bun scripts/gen-third-party-notices.ts (it needs cargo, and makes its own production-only install in a scratch folder) and commit the result. CI and cut.sh run it with --check and fail while the file is stale or a licence is not on the allow-list.