versus-incident

How Versus Creates Incidents

Incidents reach Versus two ways, and both are handled by the same notification, templating, and on-call logic:

• AI SRE Agent (auto-detect) — point the agent at your logs and it learns your normal patterns, then automatically raises an incident when a brand-new error or anomaly appears. No alert rules to maintain.
• Webhook alerts (you define) — any tool that can POST a webhook (Alertmanager, Grafana, Sentry, CloudWatch SNS, FluentBit, or your own scripts) sends incidents straight to Versus, formatted with your own templates.

Whichever source raises it, an incident is templated, fanned out to every channel you enable, and escalated to on-call if it isn't acknowledged in time.

Features

• 🤖 AI SRE Agent (Beta): An AI agent that reads your logs, learns what normal looks like, and automatically opens an incident only when something new and unexpected appears.
• 🌐 Webhook Alerts: Receive incidents from any tool that can POST a webhook — Alertmanager, Grafana, Sentry, CloudWatch SNS, FluentBit, and more.
• 🚨 Multi-channel Notifications: Fan out every incident to Slack, Microsoft Teams, Telegram, Viber, Email, and Lark (more channels coming!)
• 📝 Custom Templates: Define your own alert messages using Go templates
• 🔧 Easy Configuration: YAML-based configuration with environment variables support
• 📡 REST API: Simple HTTP interface to receive alerts
• 📞 On-Call: On-Call integrations (PagerDuty, Opsgenie, incident.io, ServiceNow)

Table of Contents

• Getting Started
• AI Agent
• Webhook Alerts
• Admin Dashboard
• Development Custom Templates
• On-Call
• Configuration
• Roadmap
• Contributing
• License

Get Started

Auto-detect incidents with the AI SRE Agent

Let the agent learn your logs and surface what's new. The AI SRE Agent has three modes:

• training — just watch and learn. No alerts.
• shadow — watch and learn, plus write a "would have alerted" log entry every time a line would have triggered an alert. Still no real alerts. Good for checking the agent's judgement before going live.
• detect — actually create incidents for lines the agent has never seen before. An AI SRE triages each one and writes the summary, severity, and suggested next steps before the incident is sent through every configured channel.

Start it in training mode — it only watches and learns, and never sends an alert until you're ready.

# Redis is used to remember where the agent left off in each log source.
docker run -d --name versus-redis -p 6379:6379 redis:7

docker run -p 3000:3000 \
  -e GATEWAY_SECRET=change-me \
  -e AGENT_ENABLE=true \
  -e AGENT_MODE=training \
  -e REDIS_HOST=host.docker.internal \
  -e REDIS_PORT=6379 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/app/data \
  ghcr.io/versuscontrol/versus-incident

The agent needs a config.yaml and an agent_sources.yaml that point it at your logs. Once it's running, review the patterns it learns on the admin dashboard at http://localhost:3000/, then switch AGENT_MODE from training → shadow → detect when you trust it.

Full walkthrough (with ready-to-copy config and a sample log generator): AI Agent — Getting Started.

Forward alerts from your existing tools

Already have monitoring? Run Versus and POST your alerts to its webhook endpoint.

docker run -p 3000:3000 \
  -e GATEWAY_SECRET=change-me \
  -e SLACK_ENABLE=true \
  -e SLACK_TOKEN=your_token \
  -e SLACK_CHANNEL_ID=your_channel \
  ghcr.io/versuscontrol/versus-incident

Versus listens on port 3000 by default and exposes:

• POST /api/incidents — webhook endpoint for monitoring tools.
• GET / — the embedded admin dashboard, open http://localhost:3000/ in your browser. For the full UI walkthrough and the build/watch scripts, see Admin Dashboard.

You can use both. The AI agent and webhook alerts are not mutually exclusive — run them together and every incident, whether auto-detected or forwarded from your tools, flows through the same channels, templates, and on-call logic.

AI Agent

The AI SRE agent is what makes Versus different: point it at your logs and it learns what normal looks like, then automatically opens an incident the moment a brand-new error or anomaly appears — no alert rules to maintain.

Configuration example with agent features:

name: versus
host: 0.0.0.0
port: 3000

# ... existing alert configurations ...

# Shared secret required for ALL admin endpoints (`/api/admin/*` and
# `/api/agent/*`). Sent by clients in the `X-Gateway-Secret` header.
gateway_secret: ${GATEWAY_SECRET}

# Storage backend for the pattern catalog, shadow log, and incident
# history. Only `file` is implemented today; `redis` and `database`
# are config stubs.
storage:
  type: file              # file | redis | database (env: STORAGE_TYPE)
  file:
    max_incidents: 1000   # rolling cap on persisted incidents

agent:
  enable: false # Use this to enable or disable the agent for all sources
  mode: training # Valid values: "training", "shadow", or "detect"
  poll_interval: 30s

  # Sources are kept in a separate file so they can be managed independently
  # (e.g. swap fixtures, per-environment lists). Path is resolved relative to
  # this config file. Override via env: AGENT_SOURCES_PATH.
  sources_path: ./agent_sources.yaml

  catalog:
    persist_interval: 30s
    auto_promote_after: 100 # In detect mode, this many sightings = "known"

  redaction:
    enable: true
    redact_ips: false
    extra_patterns: # Optional: extra regex rules to scrub before clustering
      - "(?i)password=\\S+"
      - "Authorization:\\s*Bearer\\s+\\S+"

  miner:
    similarity_threshold: 0.4
    tree_depth: 4
    max_children: 100

  regex:
    # Optional: tag any signal whose message matches this pattern
    # if none of the named rules below hit. Leave empty to disable.
    default_pattern: "(?i)error|exception|fatal|panic"
    # Named rules are tried first, in order. The first match wins.
    rules:
      - name: oom
        pattern: "(?i)out of memory|OOMKilled|java\\.lang\\.OutOfMemoryError"
      - name: db-timeout
        pattern: "(?i)(connection|query) timeout|deadlock detected"
      - name: auth-failure
        pattern: "(?i)401 unauthorized|invalid credentials|permission denied"

redis: # Required for the agent to persist source cursors across restarts
  host: ${REDIS_HOST}
  port: ${REDIS_PORT}
  password: ${REDIS_PASSWORD}
  db: 0

Explanation:

The agent section includes:

1. enable: Turn the agent on or off (default: false). When disabled, nothing extra runs — no background processes, no extra files written.
2. mode: How the agent behaves after it has learned your log patterns:
   • training: observation only — the agent learns patterns and saves them, but sends no alerts.
   • shadow: same as training, but also logs a note every time it would have sent an alert. Good for reviewing before going live.
   • detect: the agent actively sends alerts for any pattern it has never seen before.
3. poll_interval: How often the agent checks your log sources for new entries.
4. catalog: Where the agent stores the list of known patterns and how often to write updates. mode selects the storage backend — only file is supported today, which writes to data/patterns.json (the filename and directory are fixed).

Admin secret. All admin endpoints (/api/admin/* and /api/agent/*) are protected by the root-level gateway_secret (env GATEWAY_SECRET). Set it to any value you choose; clients send the same value in the X-Gateway-Secret header. When no secret is configured the admin endpoints are not registered and the agent refuses to start.

Storage. The agent's catalog and the incident history shown in the UI are persisted via the root-level storage: block (default: type: file). The file backend writes to the fixed ./data directory (/app/data in the container image).

5. redaction: Rules for automatically removing sensitive information (passwords, tokens, emails, etc.) from logs before the agent processes them.
6. miner: Controls how aggressively the agent groups similar log lines together. The defaults work well for most setups.
7. regex: Acts as a pre-filter for the agent. Only signals whose message matches at least one rule (a named entry under rules or default_pattern) are forwarded to the pattern miner and stored in the cata