| 1 |
# Peace of Mind |
| 2 |
|
| 3 |
A production operations monitor: health checks, TLS certificate tracking, remote test orchestration, peer mesh, and email alerts. Built with Rust, Tokio, Axum, and SQLite. |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
- **Rust** (stable toolchain, 2024 edition) |
| 8 |
- **Config file** at `~/.config/pom/pom.toml` (targets, peers, alert settings) |
| 9 |
|
| 10 |
## Usage |
| 11 |
|
| 12 |
PoM operates in three modes: CLI, HTTP daemon, and MCP server. |
| 13 |
|
| 14 |
```sh |
| 15 |
# Run all configured health checks once |
| 16 |
pom check |
| 17 |
|
| 18 |
# Start the HTTP API daemon (periodic checks, peer heartbeats, pruning) |
| 19 |
pom serve |
| 20 |
|
| 21 |
# Start as an MCP server (stdio transport, for Claude integration) |
| 22 |
pom |
| 23 |
|
| 24 |
# Show current status of all targets |
| 25 |
pom status |
| 26 |
|
| 27 |
# Show what version each target is running, and how far behind local HEAD |
| 28 |
pom versions |
| 29 |
|
| 30 |
# Run remote test suites via SSH |
| 31 |
pom test |
| 32 |
|
| 33 |
# Show TLS certificate expiry for monitored hosts |
| 34 |
pom tls |
| 35 |
``` |
| 36 |
|
| 37 |
### MCP tools |
| 38 |
|
| 39 |
In MCP mode, five read-only tools answer "what is live right now" without an |
| 40 |
ssh: `status_table` (every target on one line, worst first), `target_status` |
| 41 |
(one target's full condition list), `versions`, `incidents`, and `trends`. None |
| 42 |
of them can promote, deploy, or close anything. |
| 43 |
|
| 44 |
Each takes an optional `instance`. Omitted, it reads this machine's database |
| 45 |
directly and works whether or not a daemon is running here. Named, it reads that |
| 46 |
configured peer's HTTP API over the tailnet, which is the only way to see checks |
| 47 |
local to that host: systemd units and backup freshness on the production box are |
| 48 |
not observable from anywhere else. |
| 49 |
|
| 50 |
## Configuration |
| 51 |
|
| 52 |
PoM reads `~/.config/pom/pom.toml`. The config defines: |
| 53 |
|
| 54 |
- **Targets**: HTTP endpoints to monitor, with expected status codes, JSON field checks, body substring matches, and check intervals |
| 55 |
- **Peers**: other PoM instances in the mesh (URL, bearer token, heartbeat interval, grace period) |
| 56 |
- **Alerts**: Postmark API credentials, recipient addresses, per-target cooldowns (falls back to stdout in dev mode) |
| 57 |
- **TLS**: hosts to probe for certificate expiry warnings |
| 58 |
- **Tests**: SSH targets and commands for remote test suite execution |
| 59 |
- **Repo**: per-target local checkout (`path`, optional `subdir`) that `pom versions` counts the live build against. Optional; without it the commits-behind column is blank |
| 60 |
- **SyncKit fleet**: per-target readout of which SyncKit SDK versions are syncing (`base_url`, `window_days`, intervals). Reuses the alerts ingest token; informational, so an old version in the field never degrades a target |
| 61 |
|
| 62 |
## Module Overview |
| 63 |
|
| 64 |
|
| 65 |
|
| 66 |
| `main.rs` / `cli.rs` | Binary entry point, CLI argument parsing and dispatch | |
| 67 |
| `config.rs` | TOML config loading and validation | |
| 68 |
| `types.rs` | Shared domain types | |
| 69 |
| `checks/` | HTTP health checks, TLS probes, SSH test runners | |
| 70 |
| `peer.rs` | Peer mesh heartbeats, identity verification, grace periods | |
| 71 |
| `db.rs` | SQLite persistence (incidents, history, trends) | |
| 72 |
| `api.rs` | Axum HTTP API (status, trends, mesh data) | |
| 73 |
| `alerts.rs` | Email alerts via Postmark API | |
| 74 |
| `tools/` | MCP tool definitions for Claude integration, including the read-only orientation set | |
| 75 |
| `versions.rs` | Live version per target and how far it is behind the local checkout | |
| 76 |
| `display.rs` | Terminal output formatting | |
| 77 |
| `error.rs` | Error types | |
| 78 |
|
| 79 |
## License |
| 80 |
|
| 81 |
PolyForm Noncommercial 1.0.0 |
| 82 |
|