Yarrix

Website and project information: https://yarrix.io (information only; Yarrix itself never contacts it).

Yarrix is a self-hosted, open-source monitor for a small fleet (one to about a hundred hosts). It answers four questions: are the systems healthy, are the apps answering, did the backups succeed (verified at the destination), and did the scheduled jobs check in. It routes alerts to webhooks and exposes REST, SSE, MCP and a CLI.

Status: pre-1.0, preparing a first release. The features in the docs are built and covered by tests, except where a page says otherwise (restore tests for backups, for example: backups.md). Until 1.0 only the latest release and main get fixes (SECURITY.md). What has been run on real hardware is in Platform support.

Platform support#

"Not yet verified on hardware" means the code and docs follow the vendor's documentation and are covered by tests, but nobody has run the steps on that platform yet. Each platform page says what has been exercised.

Install#

Start with the quickstart: a hub, a monitored host and a test alert in about ten minutes. Docker Compose, single binaries, and recipes for Unraid, Synology and UGOS are in docs/install.md.

Documentation#

Quick start (from source)#

Requirements: Bun 1.3.5 or newer, and a stable Rust toolchain for the agent.

bun install
bun run dev          # builds the web shell and starts the hub on 127.0.0.1:7290
curl http://127.0.0.1:7290/healthz   # {"ok":true}

The hub listens on loopback by default, so a bare install is never exposed by accident. bun run dev uses port 7290, not the hub's default 7790. 7790 is the port the hub, the agent's discovery probe and the ping client use by default, so a dev hub there would be found by agents on your network and could collide with a real one. In dev, YARRIX_LISTEN fixes the port and the LAN switch, so the Network page shows them as set by the deployment.

Settings, config and data#

Yarrix keeps code, configuration and runtime state apart.

Agent enrollment tokens are minted on the hub host only, with yarrix-hub enroll create --host <id> [--ttl 24h] or --universal [--ttl 24h] [--max-uses 10]; enroll list and enroll revoke <id> manage them. The token is printed once. An admin signed in to the web app can also mint one (POST /api/v1/enrollments).

The resolved config and data directories are logged at startup. --config-dir and --data-dir flags override the variables.

Configuration files#

On first run an empty config dir gets a commented yarrix.yaml; an existing one is never overwritten. Fictional examples of every file are in examples/config/, and JSON Schemas for editor completion are in proto/config/ (bun run schemas:export regenerates them).

• Files: yarrix.yaml, defaults.yaml, alerts.yaml, hosts/<id>.yaml, checks/*.yaml. Unknown keys are errors.
• A file that fails to load keeps its last good version active. Errors carry file:line:col and are listed at GET /api/v1/config/errors (admin).
• Secrets: write ${env:NAME} or ${file:/path} in secret fields (tokens, signing keys, webhook URLs). Values never appear in API responses or logs; a plaintext secret produces a warning. An unresolved reference invalidates only its own object.
• Terminal startup command: terminal.startup_command in yarrix.yaml is the default (herdr, tmux new -A -s yarrix-{user}, ...). A host's terminal.startup_command overrides it; leaving it out inherits, and "" means a plain login shell.
• bun run apps/hub/src/index.ts config check [--config-dir DIR] validates a config dir and exits 1 on errors.

Heartbeats#

A heartbeat is a job that pings the hub (/ping/<token>, plus /start, /fail, /log, /<exit code>; GET, HEAD or POST). The token in the URL is the credential, so treat the ping URL like a password.

• A POST body (usually the tail of the job's output) is stored, up to 10 KB, and shown on the heartbeat's detail view (GET /api/v1/heartbeats/<id>). Pings are kept for 30 days (the newest 100 per heartbeat always stay). The list endpoint never returns bodies or ping paths.
• Before storing, the hub redacts common secret shapes: Authorization: header values, Bearer tokens, password=/token=/secret=/api_key= style assignments (also in JSON), AWS and GitHub-style keys, Slack tokens, user:password@ in URLs, and PEM private key blocks. This is a safety net, not a guarantee.
• Do not send secrets. Send only what you need to diagnose a failure, for example cmd 2>&1 | tail -c 2000 | curl --data-binary @- "$PING_URL/fail", and keep credentials out of commands that print their arguments.
• Full guide, including yarrix run to wrap a command: docs/heartbeats.md.

Layout#

• apps/hub: Bun server. apps/web: React + Vite UI served by the hub.
• packages/schema, packages/ui: shared contract and UI primitives.
• crates/yarrix, crates/yarrix-proto: Rust agent/CLI and protocol types.
• docs/DECISIONS.md: the architecture decisions and what was rejected.

Development#

bun test                         # TypeScript tests
bun run typecheck && bun run lint
cargo test && cargo clippy --workspace --all-targets -- -D warnings
bun run hooks:install            # enable the pre-commit leak check

See CONTRIBUTING.md. Licensed under Apache-2.0. Third-party licenses are in NOTICE and THIRD_PARTY_NOTICES.md.