Skip to content
Vellum

Vellum

Model a system. Trace a flow through it. State what the design must always do, and check it against evidence. Then give a coding agent a specification to build from.
Run Vellum on your machineModel your first system
The Vellum canvas with the model of an online shop. The actor Customer uses the system Storefront. Storefront places orders with the system Orders. Orders is expanded: a frame holds the apps Orders API and Order worker and the store Orders DB. Orders requests payment from Payments, and sends paid orders to Fulfilment. Payments authorises cards with the external system Card network. Each card shows the kind, the technology and a description, and each line has a label.

Vellum is a web app with one database. docker compose up -d starts both. An AI provider is optional, and so is GitHub.

What it looks like

Section titled “What it looks like”
The detail panel of the app Order worker on the tab Connections. It lists three outgoing relationships: to Orders DB, Payments API and Shipping worker, each with its label and its technology.
Model. Select an element to edit it. The tab Connections lists each relationship of the element.
The trace dock at event 5 of 7. Billing fails to handle the message. The canvas rings Orders.Api and Billing in red inside the frame of the system orders. The dock says 1 of 2 expectations fail.
Trace. A scenario plays one event at a time on the canvas. A failure, a retry and a dead letter show as events.
The promise ORD-014 with three obligations. ORD-014/O1 has the label Passed, ORD-014/O2 has the label Not run, and ORD-014/O3 has the label Failed.
Promises. A promise has a stable ID. Each obligation shows its evidence: passed, failed or not run.
The dialog Review acme/orders with 21 proposals in groups: binding, channel, element, message and operation. Each row names the file and the line in the repository.
Import. A scan reads a GitHub repository at one commit. Each proposal names its file and line. You accept or reject it.
The Review flyout on the tab Findings. One finding blocks Build Ready: CON-001 for the operation POST /orders, with the button Settle with a decision.
Review. Fixed rules report concerns about the design. A decision that an owner accepts settles a finding.
The Costs flyout. The estimate for one month is 894.65 USD for the known lines. One line is unknown because it has no price. The resources show in groups by element.
Costs. An estimate uses only the prices in your price book. A line with no price is unknown, never zero.

What Vellum does

Section titled “What Vellum does”

The model is the source of truth

Services, operations, channels, messages and schemas have stable IDs. The canvas, the documents and the exports are views of that model.

Every fact has a label

declared, observed-in-source, inferred, measured or unknown. An inferred fact never becomes a declared fact by itself.

A trace is declared behaviour

A scenario plays calls, messages, retries and failures over the declared contracts. The same model always gives the same events. It does not run your code.

An agent proposes, a person approves

A coding agent reads the model and exports a specification over MCP or HTTP. No token approves a promise or changes the model.

Where to start

Section titled “Where to start”
TutorialsStart an instance, model a system, import a repository and follow one promise from a question to evidence.
How-to guidesSteps for one goal: trace a scenario, declare a promise, review a design, estimate costs, connect an agent.
ConceptsWhat a trace, a finding, an estimate and a piece of evidence establish, and what they do not.
ReferenceThe HTTP API, the MCP tools, every setting, the document formats and every rule.
TroubleshootingStart-up refusals, sign-in problems, connection errors, stale results and refused requests.
RunbooksFor the operator: back up and restore, upgrade, rotate the master key, recover from a lost key.