Getting started

This walks you from a downloaded binary to a running check timer.

Install from a release

Grab the archive for your platform from the latest release. No Rust toolchain is required.

Platform	Asset
macOS (Apple silicon)	zolder-<version>-aarch64-apple-darwin.tar.gz
Windows (x86_64)	zolder-<version>-x86_64-pc-windows-msvc.zip
Linux (x86_64)	zolder-<version>-x86_64-unknown-linux-gnu.tar.gz

Each asset ships a matching .sha256.

Verify, extract, and put it on your PATH

macOS / Linux

# Verify the checksum (run from the download directory).
shasum -a 256 -c zolder-<version>-aarch64-apple-darwin.tar.gz.sha256

# Extract, then move `zolder` somewhere on your PATH.
tar xzf zolder-<version>-aarch64-apple-darwin.tar.gz
sudo mv zolder-<version>-aarch64-apple-darwin/zolder /usr/local/bin/

Windows (PowerShell)

# Compare this hash against the .sha256 file's contents.
(Get-FileHash zolder-<version>-x86_64-pc-windows-msvc.zip -Algorithm SHA256).Hash

Expand-Archive zolder-<version>-x86_64-pc-windows-msvc.zip
# Move zolder.exe onto a directory in your PATH.

macOS: clear the quarantine flag

The release binaries are unsigned. On macOS, Gatekeeper quarantines a downloaded binary; clear the flag before the first run:

xattr -d com.apple.quarantine ./zolder

From source instead

With a Rust toolchain (edition 2024) you can cargo install --git https://github.com/QGIsK/zolder, or make build from a clone to produce target/release/zolder.

Run the wizard: zolder init

zolder init is a first-run wizard. It:

1. Discovers a local Syncthing install by looking for its config.xml at the platform's usual path:

   Platform	Syncthing config.xml
   macOS	~/Library/Application Support/Syncthing/config.xml
   Linux	~/.config/syncthing/config.xml, then ~/.local/state/syncthing/config.xml
   Windows	%LOCALAPPDATA%\Syncthing\config.xml

   If it finds one and you enable the check, it reads the GUI API key and address out of it. Per ADR-0002 it only ever reads Syncthing's config — it never modifies the mesh. If no config.xml is found the syncthing check is skipped with a note.

2. Writes the API key to a 0600 file (syncthing-api-key) in zolder's config dir, so the key never lives in zolder.toml itself.

3. Prompts for the optional bits — a canary directory (a path inside a synced folder), an ntfy topic for alerts, and a heartbeat / dead-man's switch URL. Any of these can be left blank to skip.

4. Writes zolder.toml into the platform config dir. restic and zfs are not configured by the wizard — add those sections by hand when repos or a node exist (see the Configuration reference).

Where files land

zolder.toml, the API-key file, and the default zolder.json status report all live in the platform config dir, so timer runs find them regardless of the working directory:

Platform	Config dir
macOS	~/Library/Application Support/zolder
Linux	~/.config/zolder
Windows	%APPDATA%\zolder

Pass --config <path> to override the config file location for any command. zolder init refuses to overwrite an existing zolder.toml unless you pass --force.

Install the timer: zolder init --timer

zolder check is meant to run on a schedule. zolder init --timer writes and registers a platform timer that runs zolder check on an interval:

# Wizard, then install a timer that runs `zolder check` every 10 minutes.
zolder init --timer

# Choose a different interval.
zolder init --timer --interval-minutes 15

--interval-minutes defaults to 10. If zolder.toml already exists, init --timer keeps the config and just installs the timer.

What gets installed per platform:

Platform	Mechanism	File
macOS	launchd agent (sh.zolder.check, RunAtLoad)	~/Library/LaunchAgents/sh.zolder.check.plist
Linux	systemd user service + timer (OnBootSec=2min, Persistent)	~/.config/systemd/user/zolder-check.{service,timer}
Windows	Scheduled task named zolder check	(registered via schtasks)

If zolder can't register the timer automatically, it prints the exact command to run by hand — the unit file is already written, so you only need to load it.

Next steps

• Fill in the checks your machine should run — see the Configuration reference.
• Learn what each subcommand does — see Commands.
• Set up push notifications and the dead-man's switch — see Alerting.