Quickstart

Zero to a Finding in under 15 minutes. The drill needs nothing but the agent; real alerts come last.

Step	You get
1. Run the agent	AlertINT listening for alerts
2. Fire a drill	A Situation with a Finding, end to end
3. Connect an MCP client	Your AI agent reading it
4. Point Alertmanager at the agent	Real alerts flowing in

Prerequisites#

• Docker with Compose v2, or Go 1.26+ for the binary
• An LLM: an Anthropic API key, or a self-hosted endpoint (SGLang, vLLM, Ollama, LM Studio); see OpenAI-compatible endpoint
• An MCP client: Claude Code, Codex, Gemini CLI, Cursor, VS Code (GitHub Copilot), Windsurf, or any client with Streamable HTTP and custom headers

1. Run the agent#

On Kubernetes? Install the Helm chart, then continue at step 2.

Option A: Docker Compose#

AlertINT, Prometheus, and Alertmanager, already wired together:

git clone https://github.com/alertint/alertint-agent
cd alertint-agent
cp .env.example .env
# Edit .env: set the three ALERTINT_* tokens (any long random string;
# openssl rand -hex 32 works) and your LLM API key
docker compose -f docker/docker-compose.yaml --env-file .env up

Then go to step 2.

Option B: Binary#

go install github.com/alertint/alertint-agent/cmd/alertint@latest
# or download a binary from GitHub Releases

A minimal config.yaml; everything omitted has a default:

alertmanager:
  webhook_token_env: ALERTINT_WEBHOOK_TOKEN

llm:
  provider: anthropic              # or openai-compatible
  api_key_env: ANTHROPIC_API_KEY

changes:
  ingress:                         # lets the drill plant its fake deploy
    enabled: true
    webhook_token_env: ALERTINT_CHANGES_WEBHOOK_TOKEN

Fields ending in _env name an environment variable; secrets never go in the file. Export them and start:

export ALERTINT_WEBHOOK_TOKEN="$(openssl rand -hex 32)"
export ALERTINT_CHANGES_WEBHOOK_TOKEN="$(openssl rand -hex 32)"
export ALERTINT_MCP_TOKEN="$(openssl rand -hex 32)"   # also turns the MCP server on
export ANTHROPIC_API_KEY="sk-ant-..."                  # skip for an unauthenticated local endpoint

alertint serve --config config.yaml

Save ALERTINT_MCP_TOKEN in your team's secret store. You and every teammate paste it into MCP clients (step 3), long after this shell is gone.

Every option: Configuration.

2. Fire a drill#

alertint drill --config config.yaml

On Docker Compose, run it inside the agent container:

docker compose -f docker/docker-compose.yaml exec agent /alertint drill --config /etc/alertint/config.yaml

What happens:

1. It plants a fake deploy.
2. It fires a burst of clearly fictional alerts.
3. It waits out the correlation window.
4. It prints the Finding, which names the planted deploy, and an MCP command for step 3.

Every drill surface is marked: the alertint_drill="true" label, a 🧪 DRILL banner in Slack, and drill: true over MCP.

--scenario	What it shows
flagship (default)	A fake deploy, then an error burst. The Finding names the deploy.
db-outage	A database cascade with no deploy. The Finding points at the database and treats the rest as symptoms.
storm	Debug logging fills every node's disk: 14 near-identical alerts become one Incident.

Try next#

alertint drill --config config.yaml --scenario db-outage     # no deploy: the Finding points at the database
alertint drill --config config.yaml --scenario storm         # 14 alerts, one Incident
alertint drill --config config.yaml                          # repeat within the attach window: recurred ×N, no new triage
alertint drill --config config.yaml --fresh                  # a brand-new drill instead
alertint drill --config config.yaml --resolve                # clear the alerts after the Finding: Confirming recovery, then Recovered
alertint drill --config config.yaml --resolve --resolve-wait # clear them when you press Enter (for demos)
alertint drill --config config.yaml --result <incident-id>   # print a Finding again, fire nothing
alertint drill --config config.yaml --color=never            # plain output for logs; NO_COLOR also works

On Docker Compose, add the same flags to the docker compose … exec command above.

3. Connect an MCP client#

AlertINT serves MCP on port 9912; clients authenticate with ALERTINT_MCP_TOKEN. Copy-paste setup for each client: MCP clients.

Then paste the command the drill printed:

investigate incident <id> using alertint

or ask:

List active AlertINT Situations and summarize the most critical one.

4. Point Alertmanager at the agent#

Add a receiver to alertmanager.yml (full example: examples/alertmanager.yml):

route:
  receiver: alertint-agent
  group_by: [alertname, cluster, namespace, service]

receivers:
  - name: alertint-agent
    webhook_configs:
      - url: "http://<agent-host>:9911/webhook/alertmanager"
        send_resolved: true
        http_config:
          authorization:
            credentials_file: /etc/alertmanager/alertint_token

Reload Alertmanager. Every alert now reaches AlertINT, is grouped into a Situation, and gets a Finding when it warrants one.

Next steps#

To	Read
Add live metrics (lifts the metadata-only confidence cap)	Prometheus
Run triage on your own hardware	OpenAI-compatible endpoint
Post Situations to Slack	Slack
Receive selected Situation changes on your phone	ntfy
Tune grouping and everything else	Configuration
Know what it will and won't do	Scope and limits