AOS / Docs

Quickstart

This walkthrough creates the current representative three-VM scenario, installs its content-addressed I/O objects, and runs a bounded prefix with the packaged QEMU backend.

#Build Crucible

From the repository root, enter nix develop or load the direnv environment:

aos-dev build package crucible

The package includes crucible and the scenario generator used by the end-to-end determinism checks.

#Provision the execution host

An administrator must provision the dedicated cgroup-v2 and ext4 project-quota roots and an owner-only version-2 deployment file described in campaign setup. An ordinary temporary directory does not satisfy that resource contract. Select the provisioned file:

export CRUCIBLE_CAMPAIGN_DEPLOYMENT=/path/to/campaign-executor.toml

The path is a prerequisite, not a file generated by this tutorial. You can use the global --campaign-deployment PATH option instead. The package supplies the matched guest assets; it does not configure host quotas or child credentials.

#Generate the canonical scenario

./result/bin/crucible-e2e-determinism-scenario \
  --emit-scenario > representative.scenario.toml

The generator uses the typed Rust model and computes every content identity. Inspect the emitted TOML before running it; unknown fields and invalid closed vocabularies fail closed.

#Populate the object store

The scenario references immutable block and 9p objects. Install them into a local content-addressed store:

mkdir -p .crucible/store
./result/bin/crucible-e2e-determinism-scenario \
  --populate-store .crucible/store

#Run a bounded prefix

Production QEMU execution requires a durable run-state root:

mkdir -p .crucible/run-state
CRUCIBLE_RUN_STATE_ROOT="$PWD/.crucible/run-state" \
  ./result/bin/crucible \
  --store .crucible/store \
  --artifact-dir .crucible/artifacts \
  run representative.scenario.toml \
  --until virtual-time \
  --max-virtual-time 1s \
  --max-quanta 10000

Crucible discovers the matched packaged QEMU and plugin, admits one guarded process generation, and evaluates the scenario properties from the canonical event log. A failed run retains evidence beneath .crucible/artifacts. Reaching either modeled bound reports timeout with exit status 2; that is expected for a bounded prefix, not proof of a property violation. The fixture contains faults starting at eight seconds and properties with later deadlines, so this prefix does not exercise them. The repository's full determinism gate uses its own extended lifecycle configuration.

The unattended local path accepts the default --save-on never; use the dedicated save workflow when you need a durable savepoint.

#Verify determinism

Run the same scenario twice and compare canonical fingerprints and logs:

CRUCIBLE_RUN_STATE_ROOT="$PWD/.crucible/run-state" \
  ./result/bin/crucible \
  --store .crucible/store \
  --artifact-dir .crucible/artifacts \
  verify representative.scenario.toml \
  --runs 2

verify uses its own lifecycle bounds. Matching bounded outcomes establish reproducibility of those executions, not completion of the fixture's later faults and property deadlines.

Continue with scenario authoring, signal-driven faults, and the complete command reference.