What MachineFabric Is
For thirty years your operating system has answered the same question: which app opens this file? MachineFabric answers a better one: what do you want this file to become?
Right-click a file in Finder, pick Transmute, and see what’s possible. A PDF turns into searchable text, page thumbnails, an audiobook, or an answer to a question. A folder of receipts turns into a spreadsheet. A meeting recording turns into minutes. No new app to launch, no new window to learn — just a different verb on the menu you already use.
MachineFabric is a native macOS application. Files stay on your disk. Inference happens on your Mac. There is no account to create and nothing to subscribe to. Disconnect the network and the only thing that changes is which models you can download — the ones already there keep working.
This documentation explains how the moving parts fit together and how to add your own.
How It Composes
You don’t pick the steps. You pick the destination. The system composes the journey.
Drop a video. Pick “transcribe.” MachineFabric finds the path on its own — extract the audio, decode it, run it through speech-to-text — and shows you the route before it runs. Add a new cartridge tomorrow and yesterday’s files unlock new destinations on their own.
The pieces:
- Cartridges — small executables that each do one thing well. Extract text from a PDF, run a vision model, transcribe audio, query an LLM. Cartridges can be written in any language; the SDK exists in Rust, Go, Swift/Objective-C, and Python.
- Capabilities — the typed operations a cartridge offers. Each declares what it accepts, what it produces, and the tags that distinguish it from neighbours.
- The planner — given an input and a destination, it finds a path through the installed cartridges and shows you the graph before a single byte moves.
- The host runtime — spawns cartridges, manages their lifecycle in sandboxed XPC services, and routes frames between them.
The protocol underneath all of this — capability naming, dispatch, the wire format, the cartridge runtime, the planner — is CapDAG. It is specified independently of MachineFabric and documented at capdag.com/docs. This site avoids re-stating that specification; when you need to know what a cap URN canonicalizes to, what the dispatch rule actually is, or how the Bifaci wire protocol frames a request, follow the links and read it there.
Documentation Map
Using MachineFabric
| Page | What it covers |
|---|---|
| Transmute | The right-click experience: the menu, the library, runs, live progress, memory pressure |
| Models | Bring-your-own-model: HuggingFace specs, MLX/llama.cpp/Candle backends, model families, structured generation |
Building cartridges
| Page | What it covers |
|---|---|
| Getting Started | Build a cartridge from scratch in Python, end to end |
| Capabilities | What a capability is in MachineFabric, the standard ones, how routing reaches them |
| Cartridges | Cartridge structure on macOS, install layout, sandboxing, code signing, packaging as .pkg |
| SDK Reference | What each cartridge SDK actually contains today — Python (capdag), Rust, Go, Swift |
| Contributing | How cartridges, capabilities, and media defs get into the public registries |
For the protocol specification — URN syntax, the dispatch rule, specificity scoring, the wire format, the cartridge runtime, the planner, and everything else MachineFabric is built on — see the CapDAG documentation.
What MachineFabric Adds on Top
CapDAG defines a typed plugin protocol. MachineFabric is the macOS application built on it. The pieces that belong specifically to MachineFabric — and that are documented here — are:
- The Transmute experience. A Finder context-menu integration that shows the destinations a selection can reach, not the apps that can open it. The right-click is the front door; everything below it is detail.
- The library. Files you’ve added, the runs that produced things from them, the search index over the results. The library is what the application opens to; cartridges are how it grows.
- The sandboxed host. Cartridges run in an XPC service on macOS, with code signing and notarization required for distributed cartridges. The Cartridges page covers the macOS-specific install path, the
.pkgpackaging, and the host runtime details that don’t appear in the cross-platform CapDAG spec. - Bring-your-own-model. Paste a HuggingFace model id; the moment it lands every cartridge that knows how to use it picks it up. Apple’s MLX, llama.cpp, and Candle are all supported runtimes.
- Live progress. Every step of every pipeline shows what it’s doing — the page being rendered, the frame being decoded, the token being generated. Long pipelines aren’t beach balls.
- Coverage today. PDFs split into pages or rendered as images. Every common audio format converted between any pair. The same for images and video. CSV, JSON, YAML in every direction. Open the cartridges browser and they’re already there to install.
The machinery that does this work — capability matching, the planner, the cartridge runtime — is CapDAG, and the right place to read about that machinery is capdag.com.