Install, found the fleet, run the first stream

Install

An install, end to end is the whole path in the order you meet it: one curl … | sh line, what it verifies before it writes anything, and the address it leaves you at. It ends the way every route ends — the binaries on disk and nothing configured.

Set the machine up at /setup

A machine with no owner is set up in a browser. There is no owner yet, so there is nobody who could sign in to a console — which is why /setup exists and why it is the only surface that can do this. Bring the console up and open the address it prints; the installer prints those two commands for you at the end of a network install.

Six screens, and two of them deserve a word before you start:

• Your root of trust is a ceremony, and it does not repeat. The 24 words appear once. You write them on paper and type them back from the paper, and only an exact match wipes the key from the disk. Have a pen and paper ready — and, if you can, a second person — before you begin. If the machine already has a root, the wizard says so and carries on.
• The CouchDB address is reached from the machine Saphan runs on, not from the computer you are reading the page on. Over a forwarded port that distinction is the one that catches people out.

A successful setup leaves you one hand-run step: creating the CouchDB databases is not automated, and the installer names it rather than guessing at it. It is resumable, so you run the same command again afterwards and it continues from where it stopped.

The whole walkthrough — the window that opens and shuts, all six screens, and every refusal you can meet — is First run: setting the machine up at /setup. From the moment that machine has an owner, /setup closes and the address is /console.

The same acts from a terminal

The wizard is the short road, not the only one. Identity and trust material are verbs, and on a machine you are already sitting in you can run them directly:

saphan config init          # proposes identity from git or the system; you confirm the actor
saphan config show --provenance

Identity is always human-confirmed — config init with nothing to confirm against refuses rather than guessing who you are.

The one-time trust acts are described step by step in Security: mint the root, then the intermediate, then seed the identity registry (saphan identity import). Fleet verbs check that registry and refuse until it exists — deliberately: an unattributable fleet does not start. A root can also live entirely on paper, with a separate authority signing on its behalf, which is what lets a fleet admit machines without the root ever returning to a disk.

Give a project its command deck

saphan bridge init          # generates a blank-but-working <project>-bridge and registers the workspace

The bridge is the project's command deck: orders, decisions, the board, conventions — the durable documents your fleet works from.

Admit machines, seat identities

saphan machine csr --machine m2 --csr-out m2.csr          # on the new machine
saphan machine admit --machine m2 ... --csr m2.csr        # on the control plane
saphan machine seat --identity fleet-1 --machine m2 --slot 0 --backend claude-code ...
saphan machine seat --identity fleet-2 --machine m2 --slot 1 --backend codex ...
saphan machine probe --machine m2 --capability <name> ...
saphan machine probe-confinement --machine m2             # required before confined remote work

Worked flags and refusal cases: Worked examples. Local model lanes are one config section each: an endpoint URL and the name of the credential variable (Configuration).

Run the first stream

1. Write the order (section 7). Put the owner questions to yourself honestly.
2. Check the price: the order's quote and cap, and saphan fleet headroom for whether the fleet has room to run it now.
3. Dispatch: saphan dispatch command composes the exact saphan run invocation for the stream — the engine owns every composed sentence, so a dispatch is reproducible.
4. The executor works in its worktree; you watch saphan fleet show (or the dashboard, or the VS Code tree).
5. The return comes back; review evaluates it; you decide: saphan gate <stream> --gate stop2 --decision accept --ref <review-return>.
6. saphan merge <stream> — mechanics after your decision, refusing if anything is owed.
7. After the projection shows merged: saphan teardown <stream>, dispositioning every return artifact.
8. saphan cost <stream> — read what it cost against what was quoted.