Skip to content
☰
Documentation navigation +
implemented

Run a synthetic world on your machine

In this tutorial you validate a reference WorldSpec, run it locally, and read its results. Local runs are free and need no account.

You need: a checkout of the Alive repository with uv installed. Everything below runs from the repository root.

1. Look at the model catalog

uv run alive models list

Each line is a versioned model with its evidence grade. All current models are graded L1 (executed and tested); see evidence levels.

2. Validate a world

uv run alive world validate fixtures/worlds/rural-clinic.json

Expected output:

OK  rural-navigation-demo: 4 components, 2 variants, 16 assumption parameters.

Validation checks much more than the JSON Schema: that every model exists, that edges connect real ports, that parameters have the right units and ranges, and that no metric claims a higher evidence grade than its models have earned. Try breaking a port name in a copy of the file and validating again to see a typed error.

3. Run it

uv run alive run --world fixtures/worlds/rural-clinic.json --output /tmp/alive-rural.zip

The run compares the baseline variant with the treatment variant over 30 paired replications that share the same synthetic people and random draws, so differences come from the variants rather than from luck. It finishes with typed findings such as:

- [modeled_outcome] In this synthetic world, referral_completion was … across 30 paired
  replications: difference +… pp, 95% interval […].

4. Read the export

unzip -o -q /tmp/alive-rural.zip -d /tmp/alive-rural && cat /tmp/alive-rural/evaluation/limitations.md | head -20

Start with README.md and evaluation/limitations.md. AGENTS.md explains the archive to an AI assistant. manifest.json records a SHA-256 digest per replication: run the same world again on the same runtime and the digests match exactly.

Next steps

  • Change a parameter in a copy of the world (for example navigators.config.staff) and compare.
  • In the app, choose Build a world, select one of the three reference worlds, adjust bounded parameters, validate, save and estimate, then approve the displayed credit budget. The run page shows findings, metrics, trace assertions and a paged event trace. Download full run (ZIP) saves the same reproducible artifact described above. Only synthetic data is used.
  • Import and review world JSON in the app.
  • Reproduce and compare runs.
  • WorldSpec reference.