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: the wizard does not create the CouchDB databases — it names that step rather than guessing at it. You run saphan infra databases yourself; a database that is already there is left alone, so running it again is safe. What to decide first is on The CouchDB databases.

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). saphan trust init and saphan identity import need the owner present; the runbook is in Acts that need the owner present. init, bridge init, machine csr, identity enroll and machine seat do not. 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 (Orders), commit it, and put the owner questions to yourself honestly.
2. Approve it: saphan order sign <order file>. Every order a run receives needs a person's passkey approval of its exact text; an unapproved order is refused before any seat is touched.
3. Check the price: the order's quote and cap, and saphan fleet headroom for whether the fleet has room to run it now.
4. Dispatch: saphan dispatch place --order <order file> --role executor picks a free seat and starts the run (Placing a leg). saphan dispatch command instead prints the exact saphan run line for you to run yourself.
5. The executor works in its worktree; you watch saphan fleet show (or the console, or the VS Code tree).
6. The return comes back; review evaluates it; you decide: saphan gate <stream> --gate stop2 --decision accept --ref <review-return>. An owner gate asks for a one-time six-character code typed back on your terminal.
7. saphan merge <stream> — mechanics after your decision, refusing if anything is owed.
8. After the projection shows merged: saphan teardown <stream>, dispositioning every return artifact; saphan teardown <stream> --verify-archive then removes the worktree.
9. saphan cost <stream> — read what it cost against what was quoted.