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

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

Status: work in progress, not released. No version is tagged, and the data format can change. Do not put an instance on a public address yet.

{
  "requirementId": "ORD-014",
  "state": "approved",
  "current": {
    "title": "An accepted order must survive a broker outage",
    "evidenceStatus": {
      "counts": { "passed": 1, "failed": 1, "notRun": 1, "unsupported": 0, "stale": 0 }
    }
  }
}

A promise is a requirement with a stable ID that a person approves. Each check gives evidence for it, in a stated scope. A check that nobody ran counts as not run, never as a pass. This is a part of the answer of GET /api/projects/{projectId}/promises/{promiseId} at the end of the tutorial The promise loop.

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.

What is limited now

Section titled “What is limited now”
  • Imports and AI calls were tested against local stand-in servers. No run against the GitHub API or a real AI provider is recorded.
  • The hosted profile exists in the code. It is not ready for use. See Local and hosted profiles.
  • Some features have no screen yet and work through the HTTP API only: drafts, revisions, members, and the model export. Each how-to guide states this where it applies.