Pacto is to service operations what OpenAPI is to HTTP APIs.
A service's operational behavior — interfaces, dependencies, runtime semantics, configuration and readiness — is scattered across Helm values, wikis and dashboards, and drifts from what's actually running. Pacto captures it once in a validated, versioned contract (pacto.yaml), distributes it through your existing OCI registry and lets pacto diff catch breaking changes while the operator catches runtime drift. It doesn't replace OpenAPI, Helm, Terraform, Backstage or Kubernetes — it adds the operational contract layer between them, composing the interfaces you already own and adding what no single one does: ownership, dependencies, compatibility and readiness over time.
Documentation · Quickstart · Specification · Examples · Live demo
Why Pacto exists — MANIFEST.md
flowchart LR
DEV([Developer]) --> C
OA[OpenAPI spec] -. composed .-> C
JS[Config JSON Schema] -. composed .-> C
C["📋 pacto.yaml<br/>operational contract"] --> R[(OCI registry)]
R --> P["Platforms and tools<br/>CI · Kubernetes · Backstage · Crossplane"]
Pacto composes the interfaces you already own into one versioned contract, distributes it like a container image and lets whatever consumes your services — platforms, CI, runtime controllers and increasingly autonomous agents — read it instead of reverse-engineering it.
Underneath the products is one model. The contract declares intent; a collector observes a running environment and emits Evidence; the pure engine evaluatesContract × Evidence into Findings; consumers surface or act on them.
flowchart TB
A["Author intent<br/>pacto.yaml"] --> C["Contract"]
R["Running environment"] --> COL["Collector"]
COL --> E["EvidenceSet"]
C --> EV["Evaluate"]
E --> EV
EV --> OUT["Findings + Coverage"]
The stable extension boundary is the EvidenceSet, not a collector interface: a collector is any component that produces a valid EvidenceSet the engine can evaluate. The Kubernetes collector is the first shipped integration; other collectors may live inside or outside this monorepo. Pacto is modular through a stable Evidence schema — not a dynamically pluggable collector runtime. See Collectors and the evidence boundary.
The CLI, dashboard and Kubernetes operator are products built on that model — not the architecture itself. The operator is the host around the Kubernetes collector; the engine never queries Kubernetes.
flowchart LR
CLI["CLI · design-time and CI<br/>init · validate · diff · doc · push"] --> R[(OCI registry)]
R --> DASH["Dashboard · anytime<br/>graph · ownership · SBOM · readiness · docs"]
R --> OP["Operator · in-cluster<br/>hosts the Kubernetes collector · track · verify"]
OP -. runtime state .-> DASH
No sidecars and no central control plane: the CLI uses your existing OCI registry, the operator watches CRDs and the dashboard merges every source — local, OCI, Kubernetes and cache — into one view.
# Author and publish a contract (install is below)
pacto init my-service &&cd my-service # scaffold a contract bundle
pacto validate .# 3-layer validation
pacto push oci://ghcr.io/acme/svc-pacto # tag inferred from service.version# Catch breaking changes in CI
pacto diff oci://ghcr.io/acme/svc:1.0 oci://ghcr.io/acme/svc:2.0
# Explore everything in a browser
pacto dashboard # auto-detects local, OCI and K8s sourcesThe Quickstart goes from zero to a published contract in two minutes.
pactoVersion: "2.0"service:
name: payments-apiversion: 2.1.0owner:
team: paymentsdri: aliceinterfaces:
- name: rest-apitype: openapiref: interfaces/openapi.yaml # points at your existing OpenAPI specvisibility: publicdependencies:
- name: authref: oci://ghcr.io/acme/auth-pacto:2.0.0required: truecompatibility: "^2.0.0"Only pactoVersion and service are required — everything else (runtime semantics, configuration, policies and readiness) is opt-in. Each interface's ref points at a schema you already own, so a contract composes your interfaces rather than redefining them. See the Contract Reference for the full schema.
Bump a version, remove an endpoint, drop a config property — pacto diff classifies each and fails CI before the merge:
$ pacto diff oci://ghcr.io/acme/svc:1.0 oci://ghcr.io/acme/svc:2.0Classification: BREAKINGChanges (3): [NON_BREAKING] service.version (modified): service.version modified [1.0.0 -> 2.0.0] [BREAKING] openapi.paths[/predict] (removed): API path /predict removed [- /predict] [POTENTIAL_BREAKING] schema.properties.model_path (removed): schema.properties.model_path removed [- map[type:string]]breaking changes detected # printed to stderr; non-zero exit gates the mergeEverything a contract enables, from one artifact:
- Dependency graph — transitive service relationships and blast radius (the downstream services a change can affect), recursively resolved
- Ownership registry — every service by team and DRI (directly responsible individual), with per-owner compliance and readiness
- SBOM inventory — SPDX / CycloneDX package inventory and package-level diffs across versions
- Operational docs —
pacto docrenders Markdown, an offline dashboard-grade HTML site or an interactive Swagger/Scalar API explorer - Readiness scoring — operational-readiness assessment per service, surfaced in the fleet view
- Runtime verification — with the operator, whether deployed workloads still match their contract
- OCI distribution — push/pull to GHCR, ECR, ACR, Docker Hub and Harbor with local caching; signable with cosign or Notary
- Reproducibility and supply chain —
pacto.lockfor pinned resolution, gitignore-style.pactoignorefor packaging - Extensibility — out-of-process plugins generate deployment artifacts;
pacto mcpexposes contract operations to Claude, Cursor and Copilot
The dashboard merges local, OCI and Kubernetes sources into one fleet view; deploy the container image alongside the operator to combine runtime state with contract data.
Pacto composes the interface tools it sits between (OpenAPI, config schemas) and complements deploy tools (Helm, Terraform). It gets compared just as often to the platform-engineering tier — the orchestrators, provisioners and portals that act on a service. Pacto is not one of them: its job is four verbs over a single versioned OCI artifact — diff (semantic breaking changes), graph (transitive blast radius), enforce (recursive policy, fail-closed) and verify (the same artifact at design-time via the CLI and at runtime via the operator) — while making zero deployment decisions.
| Versioned artifact | Semantic diff | Dependency graph | Transitive policy | Runtime verify | Orchestrator-agnostic | Deploys? | |
|---|---|---|---|---|---|---|---|
| Score | — | — | — | — | — | ✅ | No |
| Crossplane Configuration | ✅ | — | — | — | — | — | Yes |
| KubeVela / OAM | — | — | Partial | — | — | Partial | Yes |
| Radius | — | — | ✅ | — | — | Partial | Yes |
| Kratix | — | — | — | — | — | Partial | Yes |
| Backstage / Port | — | — | Partial | — | — | ✅ | No |
| Kargo | ✅ | — | — | — | — | ✅ | Yes |
| Pacto | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | No |
✅ first-class · Partial adjacent or limited · — not in scope. A 2026 snapshot, and several of these are complementary rather than competing: a contract can gate a Kargo promotion, feed a Backstage card or front a Crossplane provisioner. The point is the combination — Pacto is the only row that is a versioned, diffable, graph-resolved, policy-enforced and runtime-verified contract that stays orchestrator-agnostic and never deploys.
What Pacto is NOT:
- Not a deployment tool — it describes services, not how to run them, and makes zero deployment decisions, which keeps it complementary to deploy engines like KubeVela, Radius and Kratix rather than competing with them
- Not a service mesh — no sidecars, no traffic interception
- Not a service catalog or portal — the dashboard renders ownership, SBOM and readiness from contracts and runtime; it feeds Backstage/Port, it doesn't replace them
- Not another configuration language — it composes the schemas you already own
See MANIFEST.md for the full rationale.
# Installer script
curl -fsSL https://raw.githubusercontent.com/TrianaLab/pacto/main/scripts/get-pacto.sh | bash
# Go
go install github.com/trianalab/pacto/v3/cmd/pacto@latest
# From source
git clone https://github.com/TrianaLab/pacto.git &&cd pacto && make buildFull documentation at pacto.run.
| Guide | Description |
|---|---|
| Quickstart | From zero to a published contract in 2 minutes |
| Contract Reference | Every field, validation rule and change classification |
| For Developers | Write and maintain contracts alongside your code |
| For Platform Engineers | Consume contracts for deployment, policies and graphs |
| CLI Reference | All commands, flags and output formats |
| Dashboard | Deploy the dashboard container alongside the operator |
| Kubernetes Operator | Runtime contract tracking and verification |
| MCP Integration | Connect AI tools (Claude, Cursor, Copilot) to Pacto via MCP |
| Plugin Development | Build plugins to generate artifacts from contracts |
| Examples | PostgreSQL, Redis, RabbitMQ, NGINX, gRPC and more |