CUTIP¶

Container Unit Templates in Python — a deterministic framework for defining, validating, and orchestrating container environments using structured YAML artifacts and Python workflows.

CUTIP is not a wrapper around docker-compose. It is an opinionated engineering layer: every container resource is a versioned, validated artifact; every deployment is a reproducible Python function.

The Model¶

Container infrastructure is organized into four composable layers:

ImageCard   ─┐
NetworkCard ─┘──▶  ContainerCard  ──▶  Unit  ──▶  Group  ──▶  workflow.py

Layer	What it represents
Card	One atomic container resource (image, network, or container configuration)
Unit	One running container instance — a ContainerCard reference
Group	A collection of Units + a Python `workflow.py` — the executable artifact
Workflow	A plain Python function `main(ctx: CutipContext)` — full control, no magic

Every artifact is a versioned YAML file. Every ref is validated before any backend is contacted.

Install¶

pip install cutip
cutip --help

Contributing? Clone the repo and use uv pip install -e . for an editable install — see Installation.

Note

cutip init, cutip tree, cutip validate, cutip show, and cutip plan run without any container runtime installed. Only cutip run requires a container backend (Podman or Docker).

Quick Look¶

# cutip/cards/containers/app.yaml
apiVersion: cutip/v1
kind: ContainerCard
metadata:
  name: app
spec:
  imageRef:
    ref: images/app
  networkRef:
    ref: networks/dev
  environment:
    ENV: production
  workdir: /app

# cutip/groups/dev/workflow.py
def main(ctx):
    ctx.container("app").start()

cutip validate
cutip plan dev
cutip run dev

CLI¶

Command	Description
`cutip init [--path]`	Scaffold workspace directories and `cutip.yaml`
`cutip tree [--path]`	Print discovered cards, units, and groups
`cutip validate [--path]`	Full schema + graph validation (no backend required)
`cutip show card <ref>`	Dump a resolved card as YAML
`cutip show unit <name>`	Show a unit's resolved card graph
`cutip show group <name>`	Show a group's units and workflow status
`cutip plan <group> [--path]`	Dry-run: print execution table, start nothing
`cutip run <group> [-b backend] [--local] [--path]`	Validate → connect → execute workflow

Full reference: CLI Reference