Triage Server

Let an AI agent (or a human) check, diagnose, and recover a service — without a host shell.

Most "give the agent ops powers" setups are bad: you either hand the model a raw shell (now it can roam the whole box and conflate unrelated subsystems), or you wire up dashboards a model can't read. Triage is the third option:

A small MCP server that exposes a handful of health/diagnose/recover tools. Each returns raw evidence AND a plain-English translation, a suggested action, and whether the fix is safe to auto-apply. The agent acts through tools — it never touches the host directly.

The policy that makes it safe

Class	Tools	Behaviour
Auto-fix safe	triage_restart_process, triage_recover	An agent may run these on its own and report after. Infra only — no data touched.
Ask before risky	triage_apply(confirm=true)	Anything that could lose data / change external state. Dry-run unless confirm=true.
Can't self-fix	(reported)	Diagnosed and handed to the human with exact steps — never faked.

The dual raw + layman output is the differentiator: the agent gets structured data to act on, and the human gets a sentence they can actually understand ("Postiz's API engine isn't running — the known cold-boot hiccup. I'll restart it.").

Tools

Tool	Kind	What it does
triage_health()	read	Containers + configured in-container processes + optional dependency ping.
triage_diagnose()	read	Health check matched to a runbook → issues with raw + plain-English + action + can_auto_fix.
triage_logs(lines)	read	Raw service log tail.
triage_restart_process(name)	safe	Restart one in-container process (pm2).
triage_recover()	safe	Recreate the service container from compose. No volumes/data touched.
triage_apply(confirm)	risky	Dry-run by default; runs the configured risky command only on confirm=true.

Configure (zero code changes)

Everything is env-driven — point it at any compose-managed service:

TRIAGE_COMPOSE=/path/to/docker-compose.yaml   # compose file
TRIAGE_SERVICE=app                            # the main container/service name
TRIAGE_LABEL="My App"                         # friendly name used in messages
TRIAGE_PROCS=backend,worker                   # optional: in-container processes to watch
TRIAGE_PROC_MGR=pm2                           # "pm2" | "none"
TRIAGE_DB_PING="docker exec app-db pg_isready"  # optional: rc 0 = dependency healthy
TRIAGE_RISKY_CMD=""                           # optional: a guarded recovery (clear a queue, etc.)
TRIAGE_RISKY_DESC="clear the stuck job queue"
TRIAGE_PORT=9500

See .env.example.

Run

pip install -r requirements.txt
python3 triage.py            # serves an MCP over streamable-http on TRIAGE_PORT

Register it with your agent runtime (any MCP client). For an always-on host service, use the included launchd template com.triage.ops.plist (macOS) — adapt to systemd on Linux.

Hard-won lessons baked in

• Agents in a container can't see host processes. Give them status tools, not a shell. With shell access a model conflates unrelated subsystems and reports false negatives. Tools keep it honest.
• Two reports, always. Structured raw for the agent to branch on; a one-sentence layman for the human. A health check the human can't read is half a tool.
• Encode the safe/risky boundary in the tool, not the prompt. "Don't clear the queue without asking" in a system prompt is a suggestion; a confirm=true-gated dry-run is a guarantee.
• docker compose ps --format json varies by version (NDJSON vs single array) — handle both.
• Recover ≠ restart. A dead process needs a restart; an unhealthy container needs a recreate. Separate tools so the agent escalates correctly.

Built by

Built by KodeKing · author Fazal Shah. We build local, private, multi-agent AI systems for teams who can't send their data to the cloud. Issues and PRs welcome.

License

MIT — see LICENSE.