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

Schemas, types & state — how state is typed and how deltas merge.

2. Processes & Steps

Processes & Steps — write the two kinds of edge.

3. Compose & run

Composites & wiring — assemble, wire, and run a composite.

4. Get data out

Emitters — record the run into a durable store.

5. Design interface-first

Templates & draft processes — 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

Workspaces & the Workbench — scaffold and start the server.

2. Ask a question

Studies — wrap one question, one emit-contract, one pass/fail bar around a composite.

3. See the result

Analyses, visualizations & report cards — figures, tables, and graded scorecards.

4. Build the argument

Investigations — group studies into a gated DAG.

5. Make it defensible

Rigor & the evidence engine — 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

Working with AI agents — the AI-free tool + swappable-plugin split and the access contract.

2. The skills

Skill reference — every /viva-* command and what it wraps.

3. The API

HTTP API reference — the endpoints agents call.

4. The shapes

On-disk schema reference — the YAML shapes agents read and write.

New science is a new study, not a patch to the model.

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.