Headless runs

Headless runs & snapshots

The headless subcommand runs the simulation with no GUI — no Ebiten, no display — and streams CSV statistics. It is the tool for long offline experiments.

go run ./cmd/vivarium headless --ticks 50000 --every 200 --save evolved.json > run.csv

Flag	Default	Description
--ticks <n>	10000	Number of ticks to simulate
--every <n>	200	Emit a stats row every N ticks
--save <file>	—	Write the final population snapshot here
--load <file>	—	Start from a saved snapshot

Snapshots

Populations can be saved to disk and reloaded to resume, share, or seed further runs.

# Run and save
go run ./cmd/vivarium headless --ticks 50000 --save evolved.json > run.csv

# Continue where it left off
go run ./cmd/vivarium headless --load evolved.json --ticks 20000

# Open the evolved population in the GUI
go run ./cmd/vivarium --load evolved.json

Pressing s in the GUI writes a snapshot too — see Controls — so you can spot something interesting live, snapshot it, and then continue it headlessly for a long run.

Reproducibility

All randomness comes from a single seeded generator. Two headless runs with the same --seed, --ticks and config produce identical CSV output, which is what makes A/B comparison of a parameter change meaningful.

go run ./cmd/vivarium headless --seed 1 --ticks 20000 > a.csv
go run ./cmd/vivarium headless --seed 1 --ticks 20000 --config tweaked.json > b.csv
diff a.csv b.csv

Any difference between a.csv and b.csv is attributable to the config change alone.