A cartridge is a small composable program

A cartridge is a small program with a precise contract: it speaks Bifaci over standard input and output, advertises typed capabilities, and handles the operations it owns.

Start from the scaffold

The supported starting point is generated from the current runtime contract:

capdag new sentiment-tagger --python
cd sentiment-tagger
python3 -m pip install capdag
capdag dev-install .
echo "I love this" | capdag sentiment-tagger

The project defines unique input and output Media URNs, builds one Cap URN, advertises it alongside the mandatory identity cap, registers an operation, and publishes a local-development manifest. Equivalent scaffolds are available for Rust, Go, and Swift.

The sentiment example delegates the judgment to classify-en with the closed label set positive,neutral,negative. A model cartridge supplies inference; the small cartridge owns the domain decision and forwards the model’s progress. That division is the useful shape: compose existing capabilities instead of embedding every dependency.

What the host does

The host discovers and starts cartridge processes, routes multiplexed Bifaci streams, carries peer calls, maps progress, propagates cancellation and errors, and monitors health. Cartridge code stays outside the engine and UI processes.

The operating-system envelope differs. macOS uses an XPC host and Apple package signing for distributed cartridges. Linux and Windows use their platform host daemons and package formats. The wire protocol and typed capability contract do not change.

Where development fits

capdag dev-install . stages an unpublished manifest under the user’s dev registry. A development alias may introduce a capability the fabric does not know, but it may not replace an alias already owned by a different Cap URN. Reinstall after a source change, rebuilding first for compiled languages.

Publishing moves the capability and media definitions into capfab and the cartridge submission into cartridge-shelf. Registry metadata, hashes, signatures, and platform packages then make the executable distributable.

Build the example end to end in Build your first cartridge.