Quickstart

About 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 shared steps. The result is a hub on this machine, this machine enrolled as a monitored host, and a test alert delivered to a small receiver you run yourself.

Nothing here needs an account anywhere. The hub never contacts yarrix.io or any other service of ours; the website at https://yarrix.io is information only.

1. Start the hub#

Path A: Docker Compose#

You need Docker with the Compose plugin.

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
docker compose up -d
docker compose logs hub | grep "First run"

The .env line matters: the container runs as a non-root user and must be able to write the two folders. The last command prints a line like First run: open http://localhost:7790/setup to create the admin account.

(To build the image from a checkout of the repository instead of pulling it: docker compose -f deploy/docker/compose.yaml up -d --build, run from the checkout, after creating config and data next to that file.)

The hub's commands run inside the container: wherever this page says yarrix-hub, use docker compose exec hub yarrix-hub.

Path B: the single binary#

Download the hub file for your system from the release page (named yarrix-hub-<os>-<arch>, for example yarrix-hub-linux-x64), and its .sha256. Check it, then run it with its own folders:

sha256sum -c yarrix-hub-linux-x64.sha256        # macOS: shasum -a 256 -c
chmod +x yarrix-hub-linux-x64
mkdir -p yarrix/config yarrix/data && cd yarrix
YARRIX_CONFIG_DIR=$PWD/config YARRIX_DATA_DIR=$PWD/data ../yarrix-hub-linux-x64

Leave it running (use a second terminal for the rest, or a service manager later). It prints the same First run: open http://127.0.0.1:7790/setup ... line. Wherever this page says yarrix-hub, run the same binary with the same two variables, for example YARRIX_CONFIG_DIR=$PWD/config YARRIX_DATA_DIR=$PWD/data ../yarrix-hub-linux-x64 enroll create --host atlas.

The first start writes a commented config/yarrix.yaml. Both paths listen on 127.0.0.1:7790 only, so nothing is exposed.

2. Create the admin#

Open the hub in a browser on this machine and choose a username, display name and password (at least 15 characters). Whoever opens the setup page first becomes the admin, for the first hour after the hub starts (restart the hub to open it again), so do this right away. The password is checked with OPAQUE, so the hub never receives it. If the hub's address is plain http:// on another machine, the connection is not encrypted: anyone on the network path can read or change what is sent, including the sign-in page. The log prints a First run: WARNING line and the web UI shows a "Not encrypted" banner. Put the hub behind HTTPS for anything beyond a machine you control. You are signed in as an admin.

That is the only account you need for this walkthrough. Real sign-in for other people (Supabase or Tailscale) is in auth.md. If you lose the password, yarrix-hub auth setup-pin on the hub machine prints a recovery PIN for /recover. Reaching the hub from another machine over plain HTTP works but is not encrypted; see Plain HTTP and HTTPS.

3. Add your first host#

An agent is one small program on the machine to monitor. It connects out to the hub, so the machine needs no open port.

In the web app. A hub with no hosts opens on Add your first host (also Config → Add a host). Give the host a name, pick its platform, and choose Agent. The next step shows the install commands for that platform (systemd or Docker on Linux, launchd on macOS, the PowerShell installer on Windows, the Unraid template, Container Manager or a boot-up task on Synology, the Docker app or systemd on UGOS) with a one-time enrollment token already filled in. Run them on the host and leave the page open: it says "atlas is reporting" when the agent connects, with its first values. For a hub on plain http://, the commands add insecure: true for you. The agent's address for the hub comes from YARRIX_PUBLIC_URL, or the address your browser used; change it on that step if the host reaches the hub differently.

For a host you would rather not install anything on, choose SSH instead. The wizard shows a public key made for that host alone and that platform's steps to authorise it (macOS Remote Login, Windows OpenSSH, DSM, UGOS, Unraid or plain Linux). Test connection signs in once and lists what it could and couldn't read, for example "SMART: needs root", before anything is saved. A key the host refuses shows ssh's own Permission denied (publickey) line.

From the command line instead, mint a one-time token for a host named atlas (any id with lowercase letters, digits, - and _):

yarrix-hub enroll create --host atlas

It prints a token starting yxe_, shown once. Get the agent file. The published Docker image's hub serves the release files at /download/agent/. An image you built from a checkout has none (it serves agent files only if built with --build-context agents=<folder of agent files>, as a release build does), and neither has the single binary: download the agent from the release page instead (or set YARRIX_AGENT_DIST to a folder of agent files and the hub serves them the same way). Then run it:

curl -fsSLO http://127.0.0.1:7790/download/agent/yarrix-linux-x64-musl      # Path A only
chmod +x yarrix-linux-x64-musl
./yarrix-linux-x64-musl agent --insecure --hub http://127.0.0.1:7790 \
  --enroll-token yxe_...

Use the file for your system (install.md lists them; macOS is yarrix-darwin-arm64 or -x64). --insecure is needed only because this hub is plain http:// on the same machine; an agent refuses a non-HTTPS hub without it. For a hub behind HTTPS, drop the flag. The agent prints enrolled as host atlas and connected. Leave it running.

Within a few seconds the host appears under Systems in the web app with CPU, memory and disks. To keep it running across reboots, see the Linux, macOS or other platform page. You do not need a host file for this host yet. The hub treats a host you enrolled (a live enrollment token or an agent holding its own token) as part of the fleet even with no config/hosts/atlas.yaml; it shows under Systems with default thresholds and is never listed as "removed from config". Add config/hosts/atlas.yaml later for thresholds, apps and checks (configuration.md). The Add host wizard accepts the same name and writes that file for you; the running agent keeps its connection. If you delete the host in the web app, its tokens go with it.

4. Send yourself an alert#

Run a receiver on this machine. It just prints what it is sent (this is a throwaway test tool, not part of Yarrix):

# receiver.py
from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        body = self.rfile.read(int(self.headers.get("content-length", 0)))
        print(self.path, body.decode(), flush=True)
        self.send_response(200)
        self.end_headers()
    def log_message(self, *a):
        pass

HTTPServer(("0.0.0.0", 9999), H).serve_forever()

python3 receiver.py

Tell Yarrix about it. In the web app, open Alerts → Routing. A hub with no alert destinations shows a form for the first one: give it a name, choose Webhook and enter the receiver's address (from inside a container, see the note on addresses below). Save it, then Send test: the receiver prints a JSON body with "event":"test". The first destination is the default and gets everything; the hub writes config/alerts.yaml for you, with a commit when the config folder is a git repository. A URL typed into the form is saved as written, and the hub warns that it is a plaintext secret. To keep a token out of the config, enter a reference such as ${file:/config/webhook-url} in the URL field and write the address into that file, as below.

By hand instead, create config/alerts.yaml:

destinations:
  local-hook:
    type: webhook
    url: ${file:/config/webhook-url}
    default: true
rules:
  - fallback: [local-hook]

and put the receiver's address in the file the URL points at. A URL can carry a token, so it is read from a secret reference rather than written in the config:

echo 'http://127.0.0.1:9999/yarrix' > config/webhook-url

For Path A, the hub runs in a container, so 127.0.0.1 is the container itself. Use an address the container can reach: http://host.docker.internal:9999/yarrix on Docker Desktop (macOS, Windows), or this machine's LAN address on Linux. The path /config/webhook-url in alerts.yaml is the in-container path of config/webhook-url. With the single binary (Path B) write the file's absolute path instead, for example ${file:/home/you/yarrix/config/webhook-url}. (Secrets in the environment work too: ${env:NAME}, but then the variable has to be passed into the container, which the compose file does not do for you.)

The hub notices the new file and loads it; yarrix-hub config check validates the folder (and exits 1 on any error).

Now fire a test alert. It needs an admin token; make one on the hub's machine:

yarrix-hub auth token create --name quickstart --scope admin
curl -fsS -X POST -H "Authorization: Bearer yx_..." \
  http://127.0.0.1:7790/api/v1/destinations/local-hook/test

The reply is {"ok":true,...}, and the receiver prints a JSON body with "event":"test". That is the same path a real incident takes (rules choose destinations, the destination formats and delivers), minus the incident. When a host goes down, an app check fails or a heartbeat is missed, the same destination receives an incident.opened event.

Where next#

• configuration.md: the files, secrets, layering and config check.
• collection-methods.md: agent, agentless SSH, relay.
• alert-routing.md: destinations, rules, email, verifying signatures.
• app-checks.md: know when a website or service stops answering.
• heartbeats.md: know when a cron job did not run.
• security.md: before you expose the hub or enable the terminal.
• Your platform: Linux, Unraid, Synology, UGOS Pro, macOS, Windows.

Clean up#

Stop the agent (Ctrl-C), the receiver, and the hub (docker compose down, or Ctrl-C). Delete the yarrix folder to remove everything, including the database.