Pacto is to service operations what OpenAPI is to HTTP APIs.
A service's operational behavior — interfaces, dependencies, runtime semantics, configuration, scaling 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 runs your services read it instead of reverse-engineering it.
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/>track · verify runtime drift"]
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 . # 4-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: "1.2"
service:
name: payments-api
version: 2.1.0
owner:
team: payments
dri: alice
interfaces:
- name: rest-api
type: http
port: 8080
visibility: public
contract: interfaces/openapi.yaml # points at your existing OpenAPI spec
dependencies:
- name: auth
ref: oci://ghcr.io/acme/auth-pacto@sha256:abc123
required: true
compatibility: "^2.0.0"Only pactoVersion and service are required — everything else (runtime semantics, scaling, configuration, policies and readiness) is opt-in. Each interface's contract 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, move a port, remove an endpoint, drop a config property — pacto diff classifies it and fails CI before the merge:
$ pacto diff oci://ghcr.io/acme/svc:1.0 oci://ghcr.io/acme/svc:2.0
NON_BREAKING service.version 1.0.0 → 2.0.0
BREAKING interfaces.port 8081 → 9090
BREAKING openapi.paths[/predict] removed
BREAKING schema.properties.model_path removed
exit status 1 # non-zero gates the mergeEverything a contract enables, from one artifact:
- Dependency graph — transitive service relationships and blast radius, recursively resolved
- Ownership registry — every service by team and DRI, 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/v2/cmd/pacto@latest
# From source
git clone https://github.com/TrianaLab/pacto.git && cd pacto && make buildFull documentation at trianalab.github.io/pacto.
| 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 consistency 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 |