Overview

What MachineFabric is

An operating system asks which app should open a file. MachineFabric asks what you want the file to become.

Right-click a file in Finder on macOS, pick Transmute, and see what is possible. A PDF can become searchable text, page thumbnails, an audiobook, or an answer to a question. A folder of receipts can become a spreadsheet. A meeting recording can become minutes. There is no new app to launch and no new window to learn; Transmute is a different verb on the menu you already use.

You use MachineFabric through FabricLoom, its desktop app: a native client on macOS and a desktop client on Linux and Windows, both over the same local engine. Files stay on your disk and inference runs on your computer. There is no account to create and no subscription. Without a network connection the only thing that changes is which models you can download; the ones already installed keep working.

This is FabricLoom’s documentation. It explains how the parts fit together and how to add your own.

How it composes

You choose the destination, not the steps. The system composes the route.

Drop a video and pick “transcribe.” FabricLoom finds the path on its own (extract the audio, decode it, run speech-to-text) and shows you the route before it runs. When you install a new cartridge, files you already have gain new destinations.

The parts:

• Cartridges are small executables that each do one thing, such as extracting text from a PDF, running a vision model, transcribing audio, or querying an LLM. Cartridges can be written in any language. The SDK exists in Rust, Go, Swift/Objective-C, and Python.
• Capabilities are the typed operations a cartridge offers. Each declares what it accepts, what it produces, and the tags that distinguish it from similar capabilities.
• The planner takes an input and a destination, finds a path through the installed cartridges, and shows you the graph before any data moves.
• The host runtime spawns cartridges, manages their lifecycle in a separate host process (a sandboxed XPC service on macOS, a host daemon on Linux and Windows), and routes frames between them.

The protocol underneath (capability naming, dispatch, the wire format, the cartridge runtime, and the planner) is CapDAG. It is specified independently of MachineFabric, and these pages don’t restate it. For what a cap URN canonicalizes to, what the dispatch rule is, or how Bifaci (the binary frame protocol that hosts and cartridges speak to each other) frames a request, read the CapDAG documentation.

Documentation map

Using FabricLoom

Building cartridges

For the protocol specification (URN syntax, the dispatch rule, specificity scoring, the wire format, the cartridge runtime, the planner, and the rest of what MachineFabric is built on), see the CapDAG documentation.

What MachineFabric adds on top

CapDAG defines a typed cartridge protocol. MachineFabric supplies FabricLoom, the desktop app, and the product workflows built on it. This documentation covers the parts that belong to MachineFabric:

• The Transmute experience. A Finder context-menu integration that shows the destinations a selection can reach, not the apps that can open it. Everything else in the product sits behind this menu.
• The library. The files you have added, the runs that produced results from them, and the search index over those results. The application opens to the library, and cartridges extend what it can do.
• Platform cartridge hosts. Cartridges run in an XPC service on macOS and in an equivalent host daemon on Linux and Windows. The Cartridges on macOS page covers the macOS install path, .pkg packaging, signing, and notarization.
• Bring-your-own-model. Paste a HuggingFace model id, and every installed cartridge that can use that model picks it up as soon as it is downloaded. Apple’s MLX, llama.cpp, and Candle are supported runtimes.
• Live progress. Every step of every pipeline reports what it is doing: the page being rendered, the frame being decoded, the token being generated.
• Coverage today. PDFs can be split into pages or rendered as images. Common audio formats convert between any pair, as do images and video. CSV, JSON, and YAML convert in every direction. These cartridges are available to install from the cartridges browser.

The capability matching, planner, and cartridge runtime that do this work are part of CapDAG, and are described in the CapDAG documentation.