Composit

Governance-as-Code for AI-generated infrastructure.

Know what you HAVE. Declare what you SHOULD have. Detect drift.

Composit is a read-only CLI that compares the infrastructure your repo declares against the governance you've agreed on — and surfaces the gap. Works with or without AI agents; the agent angle just makes the gap urgent, because agents produce declarations faster than humans review them.

nuetzliches.github.io/composit — landing page with overview and demo.

---

Install

brew install nuetzliches/tap/composit                                          # macOS / Linux
curl -fsSL https://nuetzliches.github.io/composit/install.sh | sh              # macOS / Linux, no toolchain
npx @nutz/composit --help                                                      # Node ≥18, no toolchain
cargo install --git https://github.com/nuetzliches/composit                    # any platform with a Rust toolchain
docker pull ghcr.io/nuetzliches/composit                                       # CI / no-toolchain

Prefer zero-install? Open in Codespaces — composit is on PATH after the prebuild.

---

Quickstart

Point it at your own repo:

composit init    # scaffolds a Compositfile from a scan of the current directory
composit diff    # surfaces governance violations

init runs a scan, writes a Compositfile seeded with every detected resource type (sensible headroom on the limits) and every discovered provider. Review the file, tighten the limits, then composit diff flags any drift.

---

Try the demo

composit scan --dir examples/demo-drift --no-providers
composit diff --dir examples/demo-drift --offline

examples/demo-drift/ is a synthetic "widgetshop" workspace shaped to surface three canonical drifts — an unapproved MCP provider, a :latest image outside the allowlist, and a missing required workflow. You should see:

3 errors | 0 warnings | 0 info | 7 passed

See examples/demo-drift/ for the walkthrough and examples/Compositfile for a fuller reference.

---

How it works

Three artifacts, one comparison:

1. composit-report.yaml — the IS-state. Generated by composit scan. Inventory of what exists: services, configs, providers, who created what.
2. Compositfile — the SHOULD-state. Reviewed HCL: approved providers, budgets, resource limits, policies, scan tuning. Scaffold one with composit init, then edit to match your governance.
3. composit diff — the gap. Emits terminal, JSON, YAML, or a standalone HTML report. --strict exits non-zero on errors so it works as a CI gate.

Composit doesn't deploy anything, call cloud APIs, or modify your files. It reads declarations out of the tree and compares.

---

What it scans

25 built-in scanners with fixtures under tests/fixtures/ and E2E coverage in tests/scanner_e2e.rs:

Category	Scanners
Containers	docker (compose, Dockerfile), kubernetes (manifests, Kustomize, Helm), skaffold
PaaS / hosting	fly_toml, render_yaml, vercel_json
Config as code	terraform, env_files
Ingress	caddyfile, nginx, traefik
CI/CD	workflows (GitHub Actions, Forgejo, Gitea, GitLab CI), cron, deploy_scripts
Observability	prometheus, grafana, tempo
Data	db_migrations
APIs	proto
Policy	opa_policy
Agent tooling	mcp_config, mcp_provider, agent_spec (SKILL.md, AGENTS.md, CLAUDE.md)
Source manifests	cargo_manifest (workspaces + crates), go_module

Custom file patterns via a scan { extra_patterns { … } } block in the Compositfile. New scanner? src/scanners/nginx.rs and src/scanners/opa_policy.rs are the leanest references.

---

Self-hosted

Composit scans its own repo in CI. The Compositfile at the root declares what this project's infrastructure is supposed to look like; docs/demo/self-scan.sh is the gate that runs after cargo test. Any PR that adds infrastructure (new workflow, new docker-compose) has to update the Compositfile in the same commit or CI turns red.

---

Key concepts

composit-report.yaml (IS-state)

Machine-readable inventory. Diffable line-by-line. See examples/composit-report.yaml.

Compositfile (SHOULD-state)

Declarative governance. Approved providers, budget caps, resource allow/require rules, policy references, scan tuning. See examples/Compositfile.

Agent boundary. Generated Compositfiles carry an AGENT INSTRUCTIONS header telling coding agents to leave the file alone unless the user explicitly asks for a change. The whole governance loop hinges on this: if an agent silently updates the Compositfile every time it touches infrastructure, there is no drift left to detect. The file is for humans to review; composit diff is for everyone to run.

Public Manifest (Provider Discovery)

Hosted at provider.example/.well-known/composit.json. Unauthenticated. Lets agents and teams discover providers before any contract exists. See examples/composit-manifest.json and RFC 002.

Policy Interface

OPA/Rego rules that constrain what agents can provision. The opa_policy scanner extracts each rule's package, entrypoints and metadata; composit diff evaluates deny/allow rules against the scan report and surfaces violations as policy_violation errors. See examples/policies/.

---

Attribution: AI vs. human

Composit detects who created infrastructure via git-blame and Co-Authored-By headers. This is a reporting feature, not the core value proposition.

Method	Coverage
Git author patterns (claude, dependabot, copilot)	Automatic
Co-Authored-By headers	Automatic (Claude Code, GitHub Copilot)
Team-defined labels ([ai] prefix, pre-commit hooks)	Opt-in
Cursor, ChatGPT copy-paste, API-generated commits	Not detectable

Attribution is best-effort, not authoritative. The IS-vs-SHOULD comparison works regardless of who created what.

---

Scope

Yes:

• Reading declarations from source repos and diffing them against a reviewed governance file.
• An open spec (see docs/rfcs/) that third-party providers and tools can implement.
• Attribution metadata, best-effort, honest about its limits.

No:

• Deployment or provisioning — that's Terraform, Pulumi, ArgoCD.
• Runtime monitoring — that's Datadog, Grafana.
• Service catalog — that's Backstage, Port.
• Policy evaluation — we integrate with OPA, we don't replace it.

---

Status

Phase: CLI + Spec Draft.

• CLI: composit init, composit scan, composit status, composit diff. Rust, MIT, ~175 tests, installable via brew, cargo, docker, or Codespaces today.
• Spec: RFCs 001–004 draft (report format, provider manifest tiers, contract envelope, Compositfile schema).
• Breaking changes expected on both surfaces until v1.0. They'll be called out in release notes.

→ Roadmap · RFCs

---

Origin

Born from building MCP-native infrastructure — croniq (scheduling), hookaido (events), powerbrain (knowledge) — and noticing that the missing piece was never another capability tool. It was governance over the whole picture. The control gap existed before AI; AI made it impossible to ignore.

---

License

MIT.