stackpatrol 0.2.5

Single-binary Rust CLI that monitors a server and reports to the StackPatrol control plane.
stackpatrol-0.2.5 is not a library.

stackpatrol

Single-binary Rust CLI that monitors a server and reports to the StackPatrol control plane. Alerts are delivered to you on Telegram via @StackPatrolBot.

Built by Ali Hesari — follow on X for build notes and ship updates as we drive toward v1.

Status: pre-release. v1 ship target is 2026-07. The control-plane API is still being stabilized; expect breaking changes between minor versions until v1.

Install

The fastest path on Linux is the install script — no compiler required:

curl -fsSL https://github.com/stackpatrol/stackpatrol/releases/latest/download/install.sh | sh

It downloads a pre-built static musl binary (x86_64 or aarch64), verifies its SHA-256, and drops it on $PATH.

Or install via cargo (needs a C toolchain — apt install build-essential pkg-config on Debian/Ubuntu):

cargo install stackpatrol

Either way you get a single stackpatrol binary; the stackpatrol-core crate is pulled in automatically.

If cargo install fails with linker cc not found, your server doesn't have a C compiler — use the install script above instead, or apt install build-essential pkg-config and retry. More install troubleshooting in the main README.

Quick start

On the server you want to monitor:

# 1. Pair the server with your Telegram chat.
#    Open @StackPatrolBot, /start, "Add server", paste the token here:
stackpatrol init

# 2. Verify the link works end-to-end (sends a test alert, then clears it).
stackpatrol alert-test

# 3. Tell it what to watch. All optional — pick what applies:
stackpatrol probe add docker  /srv/myapp           # docker compose project
stackpatrol probe add systemd nginx                # systemd unit
stackpatrol probe add port    localhost:5432       # TCP reachability
stackpatrol probe ls                               # see what's configured

# 4. Run the daemon. One-off for testing:
stackpatrol daemon

For a long-running install, drop the systemd unit at packaging/stackpatrol.service (in the main repo) into /etc/systemd/system/ and systemctl enable --now stackpatrol.

stackpatrol status prints a one-shot snapshot — system load, configured probes, buffered events, API reachability. Useful before walking away.

What it watches

  • Docker Compose — alerts when a service flips up/down (docker compose ps-based).
  • systemd units — alerts when a unit changes active state.
  • TCP ports — alerts when a host:port becomes unreachable.
  • Host resources — disk / memory / load with hysteresis to avoid flapping (defaults: 90% disk, 90% memory, 2 × CPU load).

Probes only emit on edge transitions, not every tick — daemon startup never produces an alert storm. Events are buffered to a 1 MiB JSONL file if the API is unreachable and replay when it recovers.

Why is the binary open source if the backend isn't?

The CLI runs on your servers and reads system state — you should be able to audit it. Authentication tokens are issued and validated server-side, so opening the CLI source doesn't undermine the business: only the control plane can issue valid tokens. Same model used by Sentry, PostHog, and Tailscale.

Links

License

MIT.