Run your first Formation

This guide runs end to end against a source build of Ato's current main branch. Every command below was last executed on macOS (arm64); the same flow is covered by Formation acceptance on Linux.

1. Prerequisites

Git and a Rust toolchain.

2. Build Ato

git clone https://github.com/ato-run/ato
cd ato
cargo build -p ato-cli

The binary is ./target/debug/ato. Confirm the form subcommand exists:

./target/debug/ato --help
./target/debug/ato form --help

3. Prepare a small app

Create a directory with a single page. No capsule.toml yet — plain sources a Preset honestly fits are synthesized, not guessed at:

mkdir -p hello-ato
cat > hello-ato/index.html <<'EOF'
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Hello Ato</title></head>
<body><h1>Hello from a formed Capsule</h1></body></html>
EOF

4. Form it on the local runtime

./target/debug/ato form hello-ato --runtime local

A successful run reports "status": "formed" with a contract_ref (the Contract K), a derivation_ref (the route D that verified, here the single-html/v1 Preset), and satisfied verification verdicts.

5. What just happened

The directory was frozen into an Initial Condition — later edits cannot change what was measured.
With no capsule.toml present, a Preset synthesized the Contract and Derivation drafts.
The candidate executed on --runtime local (Phase 1 admits exactly local).
Its Contract observations verified, so the artifact was kept with its evidence.

To author the Contract yourself instead of using a Preset, read capsule.toml. An authored file that fails to parse stops the Formation with an error — Ato never substitutes a guess for a route somebody wrote.

Return to the documentation overview.