Getting started

Prerequisites

• Docker 24+ with the Compose plugin
• Go 1.25+ (see .tool-versions)
• Node.js 20+ and pnpm 9+
• Python 3.11+ (only needed for plugin tests)
• zip / tar / standard POSIX shell tools

1. Install

Clone the repo and bring up the local stack from the repo root:

git clone https://github.com/vincent-wuhan/opskeeper.git
cd opskeeper
cp deploy/demo.env.example .env

# Build and start the full demo stack (first run takes a few minutes)
docker compose up -d --build
docker compose ps                      # wait until every service is healthy

# Verify the control plane is healthy (opskeeper serves HTTP on 8080)
curl -fsS http://localhost:8080/healthz

2. Seed a scenario

Four reproducible PostgreSQL scenarios ship in deploy/incident-events/. Seed them into incident memory with the incident-seed tool:

# Validate the datasets first (no database writes)
go run ./cmd/incident-seed -dry-run -dir deploy/incident-events

# Write all 4 scenarios into incident memory
go run ./cmd/incident-seed \
  -dsn "postgres://opskeeper:opskeeper@localhost:5432/opskeeper?sslmode=disable" \
  -dir deploy/incident-events

The seeded incidents cover connection-pool exhaustion, disk I/O saturation, lock-wait / long transaction, and replica replay lag. Inspect timelines, recall logs, and runbooks over the incident API, or browse them in the web console:

# Incident metrics + runbooks served by the control plane
curl -fsS "http://localhost:8080/v1/incidents/metrics" | jq .
curl -fsS "http://localhost:8080/v1/incidents/runbooks" | jq .

3. Open the web console

The OpsKeeper web console is a React + Vite SPA under web/. It talks to the control plane via /api/v1.

cd web
pnpm install --frozen-lockfile
pnpm dev
# → http://localhost:5173

4. Install a worker plugin

Drop the TeamHarness MCP proxy into any worker that speaks stdio MCP. It exposes 17 tools and authenticates with Bearer + HMAC. The server reads its configuration from environment variables:

cd plugins/opskeeper-teamharness

OPSKEEPER_BACKEND_URL=http://localhost:8080 \
OPSKEEPER_GATEWAY_KEY="$GATEWAY_KEY" \
OPSKEEPER_TENANT_ID=default \
python3 mcp/server.py

For the AgentTeams Dashboard plugin package, run make build-plugins and install the resulting zip from the Dashboard (hot-deploy: qwenpaw plugin install <path> --force).

Demos

After seeding, run the verification harness scenarios to confirm the manager, critic, and verifier are wired correctly. Each scenario is a self-contained compose stack with a runner container:

# From the plugin directory — alert_storm / rca_loop / recovery_verify
bash plugins/opskeeper-teamharness/eval/scenarios/alert_storm/run.sh
bash plugins/opskeeper-teamharness/eval/scenarios/rca_loop/run.sh
bash plugins/opskeeper-teamharness/eval/scenarios/recovery_verify/run.sh

Next

Read the Architecture doc to understand the data plane, the manager dispatch table, and the safety boundary.