supavision 0.4.1

AI-powered infrastructure monitoring that discovers and watches your servers intelligently

Supavision

Point it at a server, and it figures out the rest.

Supavision uses Claude to explore your infrastructure, understand what's running, and monitor it — without you writing check scripts or defining metrics.

Why Supavision?

Traditional monitoring requires you to define every check, threshold, and alert rule upfront. Supavision flips this:

• Discovery, not configuration. Point it at a server via SSH. Claude explores the system, finds running services, databases, and configs, and builds a baseline of what "normal" looks like.
• Drift detection, not threshold alerts. Instead of "CPU > 90%", Supavision detects "this service wasn't running yesterday" or "the config file changed since last check."
• Live transparency. Watch Claude work in real time — each SSH command, each tool call, each finding — via structured streaming to an xterm terminal in the dashboard.
• Zero LLM cost. Uses Claude Code CLI (included with your Claude subscription). No per-token API charges.

How It Works

Add server → Discovery (Claude explores via SSH) → Baseline → Scheduled health checks → Slack alerts

Supports: Servers (SSH), AWS Accounts, Databases (PostgreSQL + MySQL), GitHub Orgs — extensible via prompt templates.

Quick Start

pip install supavision
supavision doctor
supavision create-admin        # Create your first admin user
supavision seed-demo           # Populate with sample infrastructure data
supavision serve --port 8080

Open http://localhost:8080, sign in, and you'll see a dashboard with sample resources, health history, and live activity.

Prerequisites: Python 3.12+ and Claude Code CLI.

For development:

git clone https://github.com/devsquall/supavision.git
cd supavision
pip install -e ".[dev]"

Features

Feature	Details
Web dashboard	Real-time status, live xterm streaming of Claude's tool calls, 30-day health grid, sparklines
Command palette	Cmd+K (or Ctrl+K) global search + keyboard shortcuts (g d, g r, ? for help)
User auth	Session-based login, role-based access (admin/viewer), profile editing, user management
5 resource types	Server, AWS Account, PostgreSQL, MySQL, GitHub Organization
Structured reports	Optional typed-issue payload via submit_report tool — enables set-diff across runs, smart alerts, per-metric trends
Live session transparency	Stream-json parsing of Claude CLI — see each SSH command, tool result, and reasoning step live
Structured metrics	Schema-validated per-resource metrics with time-series history
REST API	15 endpoints with API key auth (role-scoped: admin keys for mutations, viewer keys read-only)
MCP server	7 tools for querying resources, reports, metrics, and severity trends from Claude CLI
Slack alerts	Driven by issue set-diffs, smart dedup, SSRF-protected webhooks, rate limiting
Security	CSRF protection, scrypt passwords, session management, RBAC enforcement, rate limiting
Public landing page	Standalone /landing for sharing without requiring login

CLI

Infrastructure

supavision resource-add prod-web --type server \
  --config ssh_host=10.0.1.5 ssh_user=ubuntu
supavision run-discovery <resource_id>
supavision run-health-check <resource_id>
supavision resource-set-schedule <resource_id> --health-check "0 */6 * * *"
supavision notify-configure <resource_id> --slack-webhook https://hooks.slack.com/...

Operations

supavision serve --port 8080       # Web dashboard + API
supavision run-scheduler           # Cron-based scheduling
supavision doctor                  # Health check (config + dependencies)
supavision seed-demo               # Sample data for evaluation
supavision purge --days 90         # Cleanup old runs + reports
supavision create-admin            # Bootstrap first admin user
supavision api-key-create          # Generate an API key

Using as a Library

from supavision import Store, Engine, Resource

store = Store(".supavision/supavision.db")
resource = Resource(
    name="prod-web",
    resource_type="server",
    config={"ssh_host": "10.0.1.5", "ssh_user": "ubuntu"},
)
store.save_resource(resource)

engine = Engine(store=store)
run = engine.run_discovery(resource.id)
print(f"Status: {run.status}")

Docker

docker compose up -d

Dashboard at http://localhost:8080. Data persists in the supavision-data volume.

Configuration

Variable	Default	Description
SUPAVISION_BACKEND	claude_cli	Backend: claude_cli (free, uses CLI subscription) or openrouter (API, per-token)
OPENROUTER_API_KEY	(none)	Required if backend is openrouter
SLACK_WEBHOOK	(none)	Global fallback Slack webhook URL
SUPAVISION_MODEL	anthropic/claude-sonnet-4	Model for investigation (openrouter backend only)
SUPAVISION_CHECK_INTERVAL	60	Scheduler check interval (seconds)
SUPAVISION_CLI_TIMEOUT	180	Claude CLI timeout (seconds)
SUPAVISION_SESSION_HOURS	8	Session expiry (hours)
SUPAVISION_SESSION_IDLE_MINUTES	120	Idle timeout (minutes)
SUPAVISION_COOKIE_SECURE	true	Set false for local HTTP dev (no HTTPS)
SUPAVISION_RATE_LIMIT_LOGIN	5	Login attempts per IP per minute
SUPAVISION_RATE_LIMIT_ASK	30	Ask-page queries per IP per minute
SUPAVISION_RATE_LIMIT_DEFAULT	10	Default rate limit for mutating routes
SUPAVISION_SSH_MUX_DIR	/tmp/supavision-ssh-mux	SSH multiplexing socket directory
WEBHOOK_ALLOWED_DOMAINS	(none)	Comma-separated webhook domain allowlist

MCP Server

Supavision includes an MCP server that lets Claude CLI query your monitoring data in conversations.

supavision mcp-config  # Print config for Claude CLI

7 tools available:

Tool	Description
supavision_list_resources	All resources with current severity
supavision_get_latest_report	Latest health check report for a resource
supavision_get_baseline	Discovery baseline + checklist
supavision_get_run_history	Recent runs with status and timings
supavision_get_metrics	Latest structured metrics for a resource
supavision_get_metrics_trend	Metric history over time (time-series)
supavision_get_severity_trend	Resource-level severity streak + transitions

Architecture

Resource
   |
   v
Run → Report (+ optional structured payload) → Evaluation → Alert

Single-pipeline design. Each scheduled run produces an aggregate health Report with an Evaluation (healthy / warning / critical). Reports can optionally include a typed ReportPayload with structured issues, enabling set-diffs across runs and smart Slack alerts that only fire on new/escalating problems. See ARCHITECTURE.md for details.

Tech stack: Python 3.12+, FastAPI, HTMX, xterm.js, SQLite (WAL), Claude Code CLI.

Adding Resource Types

Create src/supavision/prompt_templates/{type_name}/discovery.md and health_check.md with {{placeholder}} syntax (e.g. {{resource_name}}, {{ssh_host}}), then add an entry to resource_types.py. See ARCHITECTURE.md for the full list of placeholders and template conventions.

Security

Supavision runs AI agents that execute read-only commands on your infrastructure. Read SECURITY.md for the full threat model, tool scoping, and deployment recommendations.

Key points:

• Session-based auth with role-based access (admin/viewer); RBAC enforced server-side on every mutating route
• Credentials stored as env var references, never the actual secrets
• Infrastructure agents use allowlisted read-only commands (docker ps, systemctl status, SELECT-only SQL, DNS lookups, TLS cert inspection, bounded ping/traceroute, etc.)
• Scrypt password hashing, CSRF on all mutations, session idle timeout, audit logging
• SSRF-protected webhook dispatch with rate limiting and domain allowlist
• Database files restricted to owner-only permissions (0600)
• API keys inherit the creating user's role; last_used_at tracked for auditability

Contributing

See CONTRIBUTING.md for setup, testing, and architecture conventions.

pip install -e ".[dev]"
pytest tests/ -v          # 755 tests
ruff check src/ tests/    # Linting

License

MIT