Skip to content

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.

  1. What is Vivarium? — the Two Spines and the problem it solves.
  2. Core concepts — stores, processes, steps, wiring, the apply law, and sites/fill/ground.
  3. 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.

1. Set up

Scaffold and start the server.

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.

3. The API

The endpoints agents call.

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.