Cirdan

Cirdan

Cirdan is an on-call software repair agent. A production alert fires — Grafana, Alertmanager, or Slack. Cirdan resolves the affected service and its repo from the explicit services: registry in cirdan.yaml, reproduces the failure in an isolated runner (Docker Compose or Kubernetes), has a coding agent fix the code — your own logged-in Claude Code / Codex CLI, or an API provider — re-verifies the fix against the pinned reproduction probe and the repo's test suite, and opens a verified pull request. When policy allows, it merges, deploys, and verifies production recovery, stopping at manual_required with full evidence when recovery fails.

alert ─▶ resolve service + repo (the services: registry) ─▶ reproduce in an isolated runner
      ─▶ coding agent fixes the code ─▶ verify (pinned repro probe + sandboxed test suite)
      ─▶ verified PR (@cirdan review loop; CI checks watched) ─▶ optional merge + deploy
      ─▶ verify recovery in production

The job it does: when an alert fires at 3am for a code-shaped failure, a verified fix PR (or a completed deploy plus recovery confirmation) is waiting instead of a page.

Cirdan is deliberately not an infrastructure mapper, a topology explorer, an observability dashboard, a generic agent launcher, or a ChatOps bot. It repairs the services you register — nothing is discovered, and nothing is repaired implicitly.

Quickstart

pipx install "cirdanops[all]"      # or uv / pip / npm / brew / curl / docker — see Install
cirdan setup                       # opens the local, loopback-only setup UI

cirdan setup walks one short path and shows a readiness banner that flips to "Ready to repair" only when this install can actually fix something:

1. Choose a pathway — Use the CLI (the tools already logged in on this machine) or Use the API (managed credentials + a GitHub App). See Two ways to run.
2. Connect an alert source — a Grafana webhook (+ HMAC), native Alertmanager intake, or Slack.
3. Select repair repositories — in Source Code Connection, Cirdan lists the repos your gh login can push to; pick which ones it may repair. Only selected repositories are ever repaired.
4. Prove routing — the Alert routing step synthesizes a sample alert (or takes a real payload you paste) and must show it resolving to a selected repository and routing to a code-repair pipeline.
5. Start the daemon and post a demo alert:

cirdand serve --http
curl -X POST localhost:8090/v1/ingest/grafana -d @examples/demo/alert.firing.json

The runnable demo in examples/demo/ wires this end to end. The same checklist is available headlessly — cirdan status --checks prints the identical table and exits 1 until the install is ready. Useful setup flags:

• cirdan setup --terminal — the text step flow instead of the UI
• cirdan setup --all — run every step without prompting (scripts / CI)
• cirdan setup --system — machine-level scope in ~/.cirdan instead of a repo

Install

From PyPI (recommended):

uv tool install "cirdanops[all]"
# or
pipx install "cirdanops[all]"
pip install "cirdanops[all]"

Without Python — npm / Homebrew / curl:

npx -y @cirdanops/cli serve-mcp        # run the MCP server, zero install
npm install -g @cirdanops/cli          # or put the `cirdan` command on your PATH
brew install adanb13/tap/cirdan        # macOS / Linux (Homebrew)
curl -LsSf https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.ps1 | iex

These ship a self-contained binary — no Python 3.11+ required. Supported: macOS (arm64), Linux x64/arm64 (glibc), Windows x64. On Intel Macs, Alpine/musl, or other platforms, use the PyPI install above.

Then set it up in one command (see Quickstart):

cirdan setup              # inside a repo
# or, machine-level scope in ~/.cirdan:
cirdan setup --system

Both open the same guided setup: choose a pathway, connect an alert source + GitHub, select repair repositories, prove routing, and start the always-on daemon.

Targeted installs: cirdanops[mcp], cirdanops[api], cirdanops[slack], cirdanops[agent], cirdanops[github-app], cirdanops[secrets], or combinations like cirdanops[api,mcp]. The sandbox runners need no extras — they use the docker/kubectl CLIs already on your PATH.

Prerequisites by platform (Python 3.11+ and uv or pipx):

# macOS
brew install python@3.12 uv

# Windows
winget install astral-sh.uv

# Ubuntu / Debian
sudo apt install python3.12 python3-pip pipx
# or get uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

Docker (no Python needed):

# run the always-on repair daemon: alert receiver + isolated repair runner,
# using the host's Docker for sandboxes
docker run -d \
  -v "$PWD":/workspace:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 127.0.0.1:8090:8090 \
  ghcr.io/adanb13/cirdan

(or docker compose up with the provided docker-compose.yml)

From source (latest unreleased):

pip install "cirdanops[all] @ git+https://github.com/adanb13/cirdan.git"

Two commands are installed:

Local development (from a clone)

Contributors work from a clone with an editable virtualenv, so changes to the working tree take effect immediately — no reinstall between edits. make install creates .venv and installs the package (distribution name cirdanops) editable with the [all,dev] extras — every runtime feature plus the test toolchain:

git clone https://github.com/adanb13/cirdan.git
cd cirdan
make install     # ≈ python3 -m venv .venv && .venv/bin/pip install -e ".[all,dev]"
make test        # .venv/bin/python -m pytest tests/ -q

Requires Python 3.11+. The manual two-line equivalent works on a standard Python; make install additionally handles the pip-less-venv case (it falls back to python3 -m venv --without-pip and bootstraps pip into the venv).

The editable install puts both console scripts in .venv/bin, running working-tree code with no rebuild:

.venv/bin/cirdan setup                                    # or: .venv/bin/python -m cirdan.cli.main setup
.venv/bin/cirdand serve --http
.venv/bin/python -m pytest tests/test_slack_events.py -q  # a single test module

Common Make targets (make help lists them all):

On a headless box with no OS keyring, storing credentials during cirdan setup needs a master key in the environment first: export CIRDAN_MASTER_KEY=$(.venv/bin/python -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())').

Two ways to run: Use the CLI / Use the API

The first setup screen picks a deployment posture (deployment_mode: in cirdan.yaml), which gates everything after it:

Use the CLI (cli, the default) — Cirdan runs with the tools already logged in on this machine. GitHub writes go through your gh auth login; the coding agent is a detected, logged-in Claude Code or Codex CLI, spawned headless inside the isolated repair workspace; the sandbox runner is your local Docker (or kubectl). The happy path needs no stored keys and no GitHub App — an env-var API key and a GitHub App remain available behind explicitly labeled "Advanced" toggles.

Use the API (api) — headless and managed, for shared/enterprise deployments. Provider API keys are stored encrypted (cirdan secret; AES-256-GCM), GitHub writes go through a GitHub App (guided manifest onboarding) with short-lived per-repo installation tokens, and the enterprise security profile is derived automatically: inherited gh auth and host-spawned CLI agents are refused at config load.

Both pathways end at the same readiness contract — the setup UI banner and cirdan status --checks render the same table: repair repositories selected (each with a resolvable repo) · an alert source connected · a routing proof (a sample or live alert demonstrably resolved to a selected repository and routed to a code pipeline) · remediation.mode ∈ {develop, deliver} · a live-probed coding agent · a verified GitHub write path including access to each selected repo · git on PATH · a working sandbox runner · the daemon running. Every red row shows the exact fix command or the setup step that resolves it.

Legacy configs load forever: deployment_mode: single-user reads as cli, business as api, and the file text migrates on the next setup save.

Configuration

cirdan setup writes cirdan.yaml for you; everything is also hand-editable — see cirdan.yaml.example. The heart of the file is the services: registry: the explicit list of services Cirdan may repair, how alerts resolve to them, and where their code lives.

services:
  - name: checkout-api                 # canonical id (lowercase, node-id-safe)
    repo: acme/checkout                # "org/name" — the PR / repair target
    aliases: [checkout, checkout-svc]  # extra alert-label names for this service
    match_labels: {team: payments}     # optional exact label matchers (first match wins)
    deploy:                            # how it runs in prod + how the runner rebuilds it
      kind: compose                    # compose | k8s | helm
      compose_service: checkout-api    # defaults to the entry name
      compose_files: [docker-compose.yml]
    deploy_workflow: deploy.yml        # per-service GitHub Actions deploy (optional)
    telemetry_service: checkout        # Loki/PromQL service label; defaults to name

  - name: payments-api
    repo: acme/payments
    source_root: ~/src/payments        # local checkout (cli pathway only)
    deploy:
      kind: k8s
      namespace: prod
      workload: payments-api           # kubernetes_kind defaults to Deployment

Alerts resolve to a service by an explicit cirdan_node label, then match_labels, then a ladder of common labels (service, service_name, app, job, deployment, statefulset, pod, container, the host of instance, annotations.service, alertname) matched against names + aliases. There is no implicit default: an alert that matches nothing opens a triage incident and never auto-repairs "the only registered repo".

Routing policy. Every alert source

…