sitescope a small health monitor and status page for a few hosts

Use

Command line

One binary, every role. The daemons, the operator commands that talk to a running hub, the vault editor and a one-shot checker.

sitescope <command> [flags]

Daemons

sitescope hub -config FILE
Polls agents, runs probes, keeps history, sends mail, serves the status page and the control socket. Started by sitescope.service.
sitescope agent -config FILE
Serves this host’s report on agent.listen. Started by sitescope-agent.service.

Talking to the hub

These connect to the control socket: -socket, or else hub.controlSocket from the hub’s config (-config, $SITESCOPE_CONFIG or /etc/sitescope/config.json). With neither a socket nor a config, they stop with an error rather than guess. You need to be in the admin group.

sitescope unlock
Asks for the vault passphrase on the terminal, without echo, and sends it to the hub. The hub decrypts the vault into locked memory and runs the checks that were waiting for it. Run it again after editing the vault.
sitescope lock
Zeroes the hub’s decrypted secrets and its login cache. Credential checks go back to locked.
sitescope status
Prints whether the vault is locked, the names of the loaded secrets when it isn’t, and the number of checks.

The vault

These read and write the vault file directly: -vault, or else hub.vault from the hub’s config (found as above); with neither, they stop with an error. Run them as the hub user: sudo -u sitescope sitescope vault …. Each asks for the passphrase.

sitescope vault set NAME
Stores a secret. The value comes from stdin, or is prompted for without echo. The first set creates the vault and asks for a new passphrase twice. Names are letters, digits, _, . and -.
sitescope vault rm NAME
Deletes a secret.
sitescope vault list
Prints secret names, never values.
sitescope vault set-password
Asks twice for the detail view’s admin password and stores its bcrypt hash as admin_password_hash.

One-shot checks

sitescope check -config FILE [-match SUBSTR]
Runs every check that doesn’t need the vault once, in parallel, and prints one line per check: status, id, time taken, message. Exits 2 if any is crit. Useful for trying a configuration before deploying it. 
$ sitescope check -config config.json -match tls
ok    tls.www.example.org.https.443.v4   61ms   certificate expires 2026-12-01 (61 days), issuer E7
ok    tls.www.example.org.https.443.v6   58ms   certificate expires 2026-12-01 (61 days), issuer E7
warn  tls.mx.example.org.smtp.25.v4      212ms  certificate expires 2026-10-15 (14 days), issuer E8

What the hub contacts

sitescope probes -config FILE
Lists every destination the hub contacts (address or host, port and protocol), what it sends there and how often, when all is healthy. See Probes and alert volume.

Checking a running hub

sitescope verify -url URL [flags]

Reads the hub’s /healthz and /status.json and checks them, for use after a deploy. It only sends two GETs, without credentials. Prints one line per expectation and exits 1 if any is unmet.

flag expects
-version V /status.json’s version: exactly X.Y.Z+rev, or just the release when V has no +rev
-vault STATE the vault state: locked or unlocked
-overall STATUS the overall status: ok, warn, crit or unknown
-services N the number of services in /status.json
-checks N the number of checks listed in /status.json (class A only)
-ca FILE trust only this PEM CA for the hub’s certificate, for a hub behind a private CA
-timeout D per request; default 10s 
$ sitescope verify -url https://status.example.org -version 1.4.0+abc1234 -vault unlocked -overall ok
ok    healthz   200 ok
ok    version   1.4.0+abc1234
ok    vault     unlocked
ok    overall   ok

Other

sitescope version
Prints the version: the release plus the flake’s git revision, e.g. 1.1.0+5c6dc53 (VERSION, then the commit). The page footer and /status.json show it too.