Start here¶
This guide is organized into four parts — Foundations, Build & run models, Investigate, and Reference. You don't have to read them in order. Pick the path that matches what you're trying to do; each is a short, numbered route through the chapters that matter for it.
Two things almost everything assumes
Most hands-on work needs a workspace (a directory with a workspace.yaml and a
viva_<pkg>/ package) and a running Workbench (the dashboard server). If either is
missing, start at Workspaces & the Workbench.
Just want it running?
The Quick start is a copy-pasteable, top-to-bottom path from nothing to a running Workbench — and it's written so you can point an AI agent straight at it.
Everyone: the 20-minute mental model¶
Before any path, read these three — they're short and everything else builds on them.
- What is Vivarium? — the Two Spines and the problem it solves.
- Core concepts — stores, processes, steps, wiring, the
applylaw, and sites/fill/ground. - The stack — how the four packages layer.
Path A — Build a model¶
You want to wrap simulators as processes and run a composite.
1. Types & state¶
How state is typed and how deltas merge.
2. Processes & Steps¶
Write the two kinds of edge.
3. Compose & run¶
Assemble, wire, and run a composite.
4. Get data out¶
Record the run into a durable store.
5. Design interface-first¶
Sketch an interface before the mechanism.
Then: run it in the UI via Workspaces & the Workbench.
Path B — Turn runs into evidence¶
You want reproducible, inspectable, verdict-bearing science.
2. Ask a question¶
Wrap one question, one emit-contract, one pass/fail bar around a composite.
3. See the result¶
Figures, tables, and graded scorecards.
4. Build the argument¶
Group studies into a gated DAG.
5. Make it defensible¶
Computed-not-asserted verdicts, gates, and provenance.
Then: follow it end to end in A worked example.
Path C — Drive it with agents¶
You want AI agents to build and run investigations on your behalf.
1. How agents fit¶
The AI-free tool + swappable-plugin split and the access contract.
2. The skills¶
Every /viva-* command and what it wraps.
4. The shapes¶
The YAML shapes agents read and write.
Whichever path you take, the loop is the same: Question → Composite → Run → Verdict → Next. When you're ready for the full detail, everything is in the Reference.