Stack Guardian

stack-guardian

Status: active development -- changelog

mcp-name: io.github.LuminariSoftwares/stack-guardian

14 health checks, one command: the example stack exits 2 with 4 FAIL findings, on purpose.

A health doctor for a home AI stack -- Ollama or OpenAI-compatible nodes, NVIDIA GPUs, tailnet peers -- with graded, evidence-backed findings.

Quick start (60 seconds)

macOS / Linux (offline example run, Python 3.11+):

pip install stack-guardian

curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json curl -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json stack-guardian doctor --snapshot snapshot.json --ctx ctx.json

Windows (PowerShell), or anywhere you would rather not touch the system Python

pipx install stack-guardian

curl.exe -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/snapshot.json curl.exe -LO https://raw.githubusercontent.com/LuminariSoftwares/stack-guardian/main/examples/ctx.json stack-guardian doctor --snapshot snapshot.json --ctx ctx.json

pipx puts it in its own virtualenv and on your PATH (pip install pipx if you do not have it). uvx stack-guardian doctor --snapshot snapshot.json runs it without installing anything at all.

The example snapshot makes every shipped rule fire once, so you see each finding type without touching a real stack. The command exits 2 because the example contains FAIL findings; that is the expected result. Each line ends with the confidence grade - one run is at most (LIKELY), the same finding on a second run is (VERIFIED).

Point it at your own machines next:

stack-guardian init                       # writes nodes.json for this machine; never overwrites one

stack-guardian doctor --nodes nodes.json

init probes http://127.0.0.1:11434 to see whether Ollama is answering, and lists your tailnet peers (if tailscale is on PATH) as commented-out candidates you can move up into the file. Edit it by hand from there; the shape is in examples/nodes.json and under What it does.

From a clone instead (for writing rules or running the tests):

git clone https://github.com/LuminariSoftwares/stack-guardian.git

cd stack-guardian python -m venv .venv .venv\Scripts\activate # Windows; macOS/Linux: source .venv/bin/activate pip install -e ".[test]" # drop [test] if you only want to run it, not test it stack-guardian doctor --snapshot examples/snapshot.json --ctx examples/ctx.json python -m pytest -q

Proof

stack-guardian doctor --snapshot snapshot.json --ctx ctx.json

Run 2026-11-05 on stack-guardian 0.4.0 ( ): the command exits 2, prints worst: FAIL, and ends with:

stack-guardian: 8 finding(s) are LIKELY on one run: run again to confirm them as VERIFIED

14 findings on the example snapshot: 4 FAIL, 4 WARN, 6 INFO. The 14 checks that ship are counted from the installed package: stack-guardian 0.4.0 checks loaded from installed package: 14

Tests, 2026-11-05 ( ): 171 passed in 61.00s (0:01:00)

Standard library only, Python 3.11+, no runtime dependencies. GPUs: NVIDIA only, and only on the machine running stack-guardian.

A health doctor for a home AI stack. It collects a snapshot of your nodes (Ollama or OpenAI-compatible endpoints, loaded models, NVIDIA GPUs, tailnet peers), runs small Python rules against it, remembers the last runs, and reports findings with a confidence grade: one sample is at most LIKELY, the same finding twice in a row is VERIFIED. It exists because "the model is slow" on a multi-machine local stack has a dozen possible causes, and an agent or a person should get a graded, evidence-backed answer instead of a guess. A finding can carry a typed fix that you run on purpose, never automatically. It ships as a CLI, an MCP server for coding agents, a tiny HTTP endpoint with Prometheus metrics, and a DeepSeek Harness (DSH) plugin.

Two runs against examples/nodes.json with one state file:

# run 1

FAIL ollama.unreachable [gpu-box-2]: 1 Ollama endpoint(s) do not answer: http://100.64.0.2:11434 (LIKELY) FAIL ollama.unreachable [home-server]: 1 Ollama endpoint(s) do not answer: http://100.64.0.3:11434 (LIKELY) FAIL tailnet.peer_offline [home-server]: tailnet peer offline: home-server (LIKELY) WARN model.expiring [gpu-box]: 1 loaded model(s) unload within 60s: qwen3:8b (LIKELY) OK ollama.answering [gpu-box]: 1 endpoint(s) answer: http://127.0.0.1:11434 worst: FAIL

run 2 (same state file)

FAIL ollama.unreachable [gpu-box-2]: 1 Ollama endpoint(s) do not answer: http://100.64.0.2:11434 (VERIFIED) FAIL ollama.unreachable [home-server]: 1 Ollama endpoint(s) do not answer: http://100.64.0.3:11434 (VERIFIED) FAIL tailnet.peer_offline [home-server]: tailnet peer offline: home-server (VERIFIED) WARN model.expiring [gpu-box]: 1 loaded model(s) unload within 60s: qwen3:8b (VERIFIED) OK ollama.answering [gpu-box]: 1 endpoint(s) answer: http://127.0.0.1:11434 worst: FAIL

<!-- demo-report:end -->

That is the real output of python examples/demo_report.py: the shipped collector and rules, with a stub Ollama on 127.0.0.1 answering for gpu-box, the two placeholder tailnet addresses never contacted, and sample nvidia-smi and tailscale output so it prints the same on any machine. The shipped rules only report problems; the OK line comes from a small rule inside the script. A test fails if this block and the script disagree.

Why the grade. One run can make a finding at most LIKELY; the same finding on two runs in a row makes it VERIFIED; passing checks are not graded. On a home network a sleeping laptop, a Wi-Fi drop or a model being reloaded looks broken for a few seconds, so one bad sample is reported as a likely problem and only what persists is reported as fact.

Standard library only, Python 3.11+, no runtime dependencies.

One of four small, independent tools for people running local models: see The guardian family.

*Not affiliated with StackGuardian, the infrastructure-automation company. Same word, unrelated projects.*

Architecture

flowchart LR

nodes["nodes.json"] --> collect subgraph collect["collect: one snapshot, all nodes in parallel"] direction TB ol["Ollama /api/tags, /api/ps OpenAI-compatible /v1/models"] gpu["nvidia-smi (local node only)"] ts["tailscale status --json"] end collect --> snap[("snapshot dict")] snap --> rules["checks.d/*.py rules run concurrently; a crash becomes check.crashed"] rules --> grade["state.grade LIKELY until seen twice, then VERIFIED"] hist[("state.json last 5 runs per node")] <--> grade grade --> cli["CLI: doctor exit 0 / 1 / 2"] grade --> mcp["MCP stdio server read-only, never records"] grade --> http["serve: /snapshot, /metrics"] grade -.->|"finding.fix"| fix["doctor --fix ID dry run unless --apply; snapshot + audit line"]

Design decisions

Each is written up with its alternatives in docs/adr/.

• Standard library only (ADR 0001). pip install pulls nothing else, so it installs on any machine with Python 3.11. Trade-off: the HTTP client, JSON-RPC loop and Prometheus renderer are hand-written and have to be tested here.
• Rules are plain Python files in a folder (ADR 0002). A rule is a function (snapshot, ctx) -> finding | list | None; a rule that raises becomes a check.crashed WARN, so a buggy rule never reports a broken stack. Trade-off: rules run in-process with your privileges; only load rule folders you trust.
• Confidence from history, not from one sample (ADR 0003). One run is at most LIKELY; two bad runs in a row are VERIFIED. Trade-off: a real outage needs a second run before it is VERIFIED, and the history is a local file.
• Typed fixes, dry run by default (ADR 0004). Exactly three actions, never a shell string from a rule; nothing changes without --apply, and every applied fix leaves a snapshot and an audit line. Trade-off: anything outside the three actions has to be done by hand.
• Agent-facing surfaces are read-only (ADR 0005). The MCP server and the HTTP endpoint never fix, never write the run history, and serve binds to loopback unless told otherwise. Trade-off: an agent can diagnose but must hand the fix back to a person.

For coding agents

• MCP server (any MCP client): stack-guardian-mcp speaks MCP over stdio with three read-only tools, stack_health, stack_snapshot and stack_explain. See MCP server for client configs and the tool reference.
• DSH plugin (npm install dsh-stack-guardian, source in dsh/, Node 20+): adds one line at the start of a DeepSeek Harness session when the doctor reports WARN or FAIL, and nothing otherwise. It runs stack-guardian doctor --json --quiet, so set STACK_GUARDIAN_NODES to your nodes file in the harness environment.
• Watching and scraping: stack-guardian doctor --watch 30 --json prints one JSON object per finding that changes state (new, resolved, severity change), so an agent can tail it; stack-guardian-serve --nodes FILE also answers GET /metrics in Prometheus text format.

MCP server

stack-guardian-mcp (also stack-guardian mcp) speaks MCP over stdio (JSON-RPC 2.0, protocol 2024-11-05). It needs a nodes file (examples/nodes.json); give its path with --nodes FILE or the STACK_GUARDIAN_NODES environment variable. Optional: --ctx FILE (rule settings), --state FILE (run history to grade against), --ttl SECONDS (how long one snapshot is reused, default 10).

Run it without installing anything:

uvx stack-guardian mcp --nodes /path/to/nodes.json

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "stack-guardian": { "command": "uvx", "args": ["stack-guardian", "mcp"], "env": {"STACK_GUARDIAN_NODE