cutip 0.1.2

Container Unit Templates in Python — a deterministic framework for building container workloads

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
VolumeCard  ─┘

Layer	What it represents
Card	One atomic container resource (image, network, volume, or container config)
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

Or install from source with uv:

git clone https://github.com/joshuajerome/cutip && cd cutip
uv pip install -e .
cutip --help

[!NOTE] cutip init, cutip tree, cutip validate, cutip show, and cutip plan run without any container runtime installed. Only cutip run requires Podman.

---

Quick Look

# cutip/cards/images/app.yaml
apiVersion: cutip/v1
kind: ImageCard
metadata:
  name: app
spec:
  source: build
  context: resources/buildtime
  dockerfile: resources/dockerfiles/app.dockerfile
  tag: latest

# 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> [--local] [--path]	Validate → connect → execute workflow
cutip group ls	List all groups in the workspace
cutip unit ls	List all units in the workspace
cutip card ls	List all cards in the workspace

cutip run connects to the Podman socket over SSH by default. Pass --local to use the local socket directly (useful in CI or rootless setups).

---

vars.yaml

Workspace variables are declared in cutip/vars.yaml with two sections:

required:
  ssh_private_key: ""   # must be filled in — cutip fails fast if empty

generated:
  data_dir: ".my-data"  # cutip creates this directory automatically

CUTIP validates all {{ vars.key }} references in cards before any container backend is contacted — missing or empty required values surface as a clear error, not a runtime failure.

---

Documentation

Full documentation at joshuajerome.github.io/cutip

Section	Contents
Getting Started	Installation, quickstart, workspace layout
Concepts	The 4-layer model, cards, units, groups, graph resolution
Reference	CLI flags, card schemas, workflow contract, exceptions
Guides	Podman setup, writing workflows, CI/CD

---

License

MIT