First run: setting the machine up at /setup

Every route above ends the same way: the machine payload on disk and nothing configured. A machine with no owner is set up in a browser, at /setup, and that is the only surface that can do it — there is no owner yet, so there is nobody who could sign in to a console.

Bring the console up and open the address it prints:

saphan bus reconcile --workspace ~/saphan     # the record must exist — see below
saphan-gateway start --workspace ~/saphan --listen 127.0.0.1:8788
# then open http://127.0.0.1:8788/setup

install.sh prints exactly these two commands at the end of a network install, and --serve makes it run them for you.

The window is narrow by construction, and it is narrow in a specific direction. /setup serves only while this workspace's record exists and carries no console principal. So:

That last row is why bus reconcile comes first. It is also the answer to the obvious attack: you cannot get the wizard back by removing a file.

Remote machines

The gateway speaks plaintext and binds loopback always — there is no flag that changes it, because the design is that TLS is terminated by a proxy in front of it. To set up a machine you are not sitting at, forward the port:

ssh -N -L 18788:127.0.0.1:8788 <that machine>
# then open http://127.0.0.1:18788/setup

The six screens

1 — Your account. You are the owner; everyone else is added later from inside Saphan.

The alias is the one field worth reading twice: it is your login to the console, it signs your decisions, and it authors the commits agents make as you. The password floor is the engine's own number, not the page's, and there is no reset email — if you lose it you reset it from a terminal on that machine.

2 — Your root of trust. One key signs for everything Saphan will ever say is yours.

This screen is a ceremony and it does not repeat. The 24 words appear once. You write them on paper, and then you type them back from the paper — only an exact match wipes the key from the disk, and after that the paper is the only copy. Have a pen, paper and, if you can, a second person present before you press Mint the root key. A mismatch names the positions that differ and leaves the key where it is, so a typo costs a retry and not the machine.

If this machine already has a root — the usual case for a fleet machine, where the root was born elsewhere — the wizard says so and carries on from there.

3 — Where your work lives. One folder holds the record, the state and the worktrees.

Check folder is not decoration: nothing existing is ever overwritten, and if something is in the way the check names the exact file.

4 — CouchDB. Saphan keeps law and evidence there.

The address is reached from the machine Saphan runs on, not from the computer you are reading the page on — so localhost here means that machine. This is the step that catches people out when they are setting up over a forwarded port. Continue unlocks only when the test passes, so a wrong address is refused here rather than halfway through the install.

What this screen writes. The address lands in your configuration as channel.base_url and evidence.base_url. The username and password land in a file beside the configuration, mode 0600:

~/.saphan/config          channel.credentials_env  = "SAPHAN_COUCHDB_CREDENTIALS"
                          channel.credentials_file = "…/couchdb.creds"
~/.saphan/couchdb.creds   SAPHAN_COUCHDB_CREDENTIALS=<username>:<password>   (0600)

⛔ The configuration never carries the password itself — only the variable's name and the file's path. That is the same name-only discipline every other credential in this ladder follows, and it is why the config file can be read, copied and reviewed without leaking anything. A system-wide install puts both under the system config root instead (Per-user vs system-wide state (the --system flag)).

The environment still wins. If SAPHAN_COUCHDB_CREDENTIALS is exported in the process that needs it, that value is used and the file is not read — so a machine already configured that way is unaffected by anything this screen writes.

Don't have one yet? The screen carries the short compose sequence inline. It can also point at a runbook directory beside the install, but ⚠ no delivery route installs one today — the screen checks whether the directory is there and says so plainly when it is not, rather than naming a path that is not on the disk. The steps that directory is meant to hold are on this site: CouchDB: the one step that is left to your hand.

5 — Ready. Nothing has changed yet; this screen is the whole plan before the button.

It lists what will happen, and separately the two things that need a yes: letting Saphan run the checks your project already uses, and letting agents commit their own work in this folder. Both are per-folder, both are reversible, and your answer is recorded either way.

One row on that list is a refusal, and it is deliberate. Setting the CouchDB databases up is not automated: the installer names that step, does not guess at it, and carries on with everything after it. So a successful setup leaves you one hand-run step, and the installer is resumable — you run the same command again afterwards and it continues from where it stopped. ⇒ That step is written out here: CouchDB: the one step that is left to your hand.

6 — Done. The last screen hands you the console and the machine is set up. From here on the machine has an owner, so /setup is closed and the address to use is /console.

If the wizard refuses

Every refusal on these screens names what it measured. The three that are worth knowing in advance:

• A 404 at /setup means the window is shut — read the table above; the usual cause on a fresh machine is that bus reconcile has not run.
• The CouchDB test fails while curl works from your desk. Almost always the address is being resolved from the wrong machine; see the note on screen 4.
• The read-back does not match. The ceremony names the positions that differ and keeps the key. Nothing is lost; type them again from the paper.