stackpatrol 0.2.4

Single-binary Rust CLI that monitors a server and reports to the StackPatrol control plane.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# stackpatrol

Single-binary Rust CLI that monitors a server and reports to the [StackPatrol](https://stackpatrol.dev) control plane. Alerts are delivered to you on Telegram via [@StackPatrolBot](https://t.me/StackPatrolBot).

> **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:

```sh
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):

```sh
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](https://github.com/stackpatrol/stackpatrol#troubleshooting-install).

## Quick start

On the server you want to monitor:

```sh
# 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](https://github.com/stackpatrol/stackpatrol)) 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

- Repo: <https://github.com/stackpatrol/stackpatrol>
- Site: <https://stackpatrol.dev>
- Telegram bot: [@StackPatrolBot](https://t.me/StackPatrolBot)

## License

[MIT](https://github.com/stackpatrol/stackpatrol/blob/main/LICENSE).