Skip to main content

Cirdan

PyPI Python Downloads CI License Stars

Cirdan is a standalone AI infrastructure cartographer and operations daemon — Graphify for live infrastructure.

It installs into AI agents like a skill, but instead of graphing only code, it fingerprints and graphs the live infrastructure the agent can access: Docker, Kubernetes, cloud accounts, IaC, databases, telemetry. It watches that graph continuously, detects incidents, and gives agents (and humans) a structured way to understand and operate the system.

Cirdan fingerprints the system.
Cirdan graphs the system.
Cirdan watches the system.
Cirdan lets the agent operate inside the system using the access the agent already has.
Cirdan generates views only when the human asks to see something.

Install

From PyPI (recommended):

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

Targeted installs: cirdanops[mcp], cirdanops[api], cirdanops[terraform], or combinations like cirdanops[terraform,mcp]. The Docker/Kubernetes/AWS/systemd adapters need no extras — they use the 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 daemon against your host's Docker, watching the current directory
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:

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

Two commands are installed:

Command What it is
cirdan Human/agent CLI
cirdand Long-running Always ON daemon

First map

cirdan map .

This fingerprints the environment (repo files and live runtimes the session can reach), builds the graph, and writes:

cirdan-out/
├── infra.html          # interactive infrastructure map
├── INFRA_REPORT.md     # plain-English report
├── infra.graph.json    # machine-readable graph for agents
├── fingerprint.json    # evidence-backed environment classification
├── access.json         # what this session can currently reach
├── services.json
├── dependencies.json
├── runtime-state.json
├── incidents/          # active.json + history.jsonl
├── views/generated/    # on-demand Agentic UI views
└── audit.jsonl         # everything Cirdan observed, generated, executed, verified

The access model

Cirdan inherits the agent's execution context. It is not a permission manager; it is a mirror. If the session can read the repo, run shell, reach /var/run/docker.sock, use kubectl, or call AWS — Cirdan can use the same context, and nothing more. Run cirdan access . to see the live capability report.

Commands

cirdan map .                        # full pipeline: fingerprint → graph → artifacts
cirdan fingerprint .                # what is this system? (with confidence + evidence)
cirdan access .                     # capability mirror for the current session
cirdan query "what depends on postgres?"
cirdan query "what broke in the last hour?"
cirdan query "what can the agent do here?"
cirdan show "show me the infrastructure map"
cirdan show "show checkout-api as a dependency graph"
cirdan show "show last night's incidents as a timeline"
cirdan incidents                    # detection pass + list
cirdan explain <incident-id|node>   # evidence-backed explanation
cirdan actions list <node>          # what can be done with current access
cirdan actions run <action-id> --yes
cirdan verify <act-record-id>       # did the system actually recover?
cirdan watch .                      # foreground event stream
cirdan serve-mcp                    # MCP server over stdio
cirdan install --project            # teach agents in this repo to use Cirdan

Always ON

cirdand serve                        # watch, refresh, detect, export — forever
cirdand serve --mcp                  # + MCP (stdio)
cirdand serve --http --mcp --host 0.0.0.0 --port 8090   # shared team server

The daemon runs supervised loops: access refresh, fingerprint refresh, graph refresh, Docker/Kubernetes event watching, telemetry ingestion, incident detection, verification, and artifact export. A crashing loop logs and restarts; it never takes the daemon down.

Agent integration

cirdan install --project             # all platforms, into this repo
cirdan install --platform claude     # .claude/skills/cirdan/SKILL.md + CLAUDE.md + .mcp.json
cirdan install --platform codex      # AGENTS.md + .codex/cirdan.md
cirdan install --platform cursor     # .cursor/rules/cirdan.mdc + .cursor/mcp.json
cirdan install --platform gemini     # GEMINI.md
cirdan install --platform generic    # .agents/skills/cirdan/SKILL.md + AGENTS.md

Installs are idempotent and never touch content outside Cirdan's own marker block. MCP tools include query_infra_graph, get_node, get_neighbors, shortest_path, get_recent_errors, get_logs, get_state, list_incidents, explain_incident, list_available_actions, execute_action, verify_action, generate_view, and more.

The graph

Every node and edge carries evidence and a confidence label (EXTRACTED, INFERRED, AMBIGUOUS, UNKNOWN):

{
  "source": "service:checkout-api",
  "target": "database:postgres-prod",
  "relation": "CONNECTS_TO",
  "confidence": "INFERRED",
  "evidence": ["DATABASE_URL references postgres://postgres-prod… in k8s/checkout.yaml"]
}

Cirdan maintains a static graph (what the repo says should exist: Compose, Kubernetes YAML, Terraform/OpenTofu, Helm, CI, SQL, nginx, systemd units) and a live graph (what actually exists: Docker Engine, Kubernetes API, AWS, systemd, Prometheus), merges them, and reports drift — declared-but-not-running, running-but-undeclared, degraded capacity, unhealthy state.

Actions and verification

Cirdan detects which operations are technically possible with the session's access (docker restart, kubectl rollout restart, systemctl restart, …), exposes them as graph-attached capabilities, executes only through the session's own tools, records pre/post state in the audit trail, and verifies the outcome (workload ready, health checks passing, error clusters quiet). There is no separate credential store and no privilege escalation.

HTTP API

With the [api] extra, cirdand serve --http exposes /health, /fingerprint, /graph, /graph/query, /services, /incidents, /actions, /views/generate, /audit, and a minimal OTLP/HTTP JSON receiver at /v1/logs. Add --mcp to mount the MCP server at /mcp.

Configuration

Zero config works. cirdan.yaml refines it — see cirdan.yaml.example.

License

Apache-2.0

Metadata

Release files for cirdanops 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cirdanops 0.1.1
File Size Uploaded Provenance Actions
cirdanops-0.1.1.tar.gz 92.3 kB With provenance Details for cirdanops-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cirdanops 0.1.1
File Interpreter ABI Platform Actions
cirdanops-0.1.1-py3-none-any.whl Python 3 none any Details for cirdanops-0.1.1-py3-none-any.whl

Total release size: 202.4 kB

Release files / cirdanops-0.1.1.tar.gz

Download URL cirdanops-0.1.1.tar.gz
Size 92.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f2b053403d8447061d518dc78347ba844f6dca71d0064a1c8ce4033106fdca8b
BLAKE2b-256 checksum
How to use checksums
f17964bbb0e6e356ef4d0fb6e53b40aa70381f01e03d67fbd97112762fba78c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.

Transparency log

Release files / cirdanops-0.1.1-py3-none-any.whl

Download URL cirdanops-0.1.1-py3-none-any.whl
Size 110.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
24f0a3d08c8b17e4050774fb8982a7b870e49d39a6b0abfdd72521ad1b39db7a
BLAKE2b-256 checksum
How to use checksums
74e2070540d2ed67e72bd9acb0356f2c6d0c044f51e063ed670e4573bf462b47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.

Transparency log

Security for cirdanops 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cirdanops-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page