Octantis

Intelligent infrastructure monitoring agent for Kubernetes, Docker, and AWS. Receives metrics and logs via OTLP, uses an LLM to autonomously investigate and classify incidents, and notifies Slack/Discord with a concrete remediation plan.

List of Contents

• How it works
• Container Image
• Running Octantis
  • Local Kind Cluster (quickstart)
  • Existing Kubernetes Cluster
  • From Source
• Configuration
• MCP Servers
• Severity Levels
• Contributing
• Documentation

How it works

OTel Collector ──OTLP──► Octantis ──MCP──► Grafana / K8s / Docker / AWS
                              │
                              ├── LLM (Anthropic / OpenRouter / Bedrock)
                              │
                              └──► Slack / Discord (remediation plan)

1. Receive — OTLP metrics/logs from OpenTelemetry Collector (gRPC :4317, HTTP :4318)
2. Filter — Drop health checks, benign patterns, and deduplicate via fingerprint cooldown
3. Detect — Auto-detect source platform (K8s, Docker, AWS) from OTLP resource attributes
4. Investigate — LLM autonomously queries Prometheus (PromQL), Loki (LogQL), and platform tools via MCP
5. Analyze — Classify severity (CRITICAL / MODERATE / LOW / NOT_A_PROBLEM) with confidence score
6. Plan — Generate actionable remediation steps
7. Notify — Send to Slack and/or Discord (only if severity >= threshold)

Container Image

ghcr.io/vinny1892/octantis:latest

Published automatically by CI on every push to master. Pin to a specific commit SHA for production (e.g., ghcr.io/vinny1892/octantis:dba131d).

Running Octantis

Local Kind Cluster (quickstart)

The fastest way to try Octantis. The dev/ directory contains scripts that create a Kind cluster with a full observability stack (Prometheus, Grafana, Mimir, OTel Collector, MetalLB, MCP servers, and Octantis itself) — everything needed to run end-to-end locally.

# Prerequisites: Docker, Kind, kubectl, Helm

# 1. Configure secrets
export OPENROUTER_API_KEY="sk-or-..."
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

# 2. Create the cluster
bash dev/setup.sh

See dev/README.md for full details (architecture, secrets, troubleshooting).

Existing Kubernetes Cluster

For deploying Octantis to a real cluster (EKS, GKE, AKS, etc.), use the example manifests:

# 1. Create secrets
kubectl create secret generic octantis-secrets \
  --namespace monitoring \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-... \
  --from-literal=GRAFANA_MCP_API_KEY=glsa_...

# 2. Deploy MCP servers + Octantis
kubectl apply -f examples/kubernetes/

See examples/kubernetes/ for the manifests. Customize the image, model, and notification settings in the ConfigMap.

Image: ghcr.io/vinny1892/octantis:latest

From Source

To run Octantis outside a cluster (requires Python 3.12+ and uv):

uv sync
cp .env.example .env   # edit with your keys
uv run octantis

See Onboarding — Local Development for full setup details.

Configuration

All settings via environment variables. See .env.example for the full list.

Key settings:

MCP Servers

Octantis connects to MCP servers via SSE using a slot model (max 1 observability + 1 platform):

Platform is auto-detected from OTLP resource attributes (K8s → Docker → AWS). Override with OCTANTIS_PLATFORM.

Severity Levels

Contributing

See CONTRIBUTING.md.

Documentation

• Architecture Overview — data flow and design decisions
• Filter Pipeline — event ingestion and pre-filtering
• LangGraph Agent — investigation, analysis, planning, and notification
• Onboarding — setup guide and code map
• Licensing — dual-license model (AGPL-3.0 core, Apache-2.0 SDK), plan tiers, and AGPL FAQ