Central servers: saphan-gateway and saphan-oauth

Everything above this section puts the machine payload on a machine. This section is about what serves a fleet centrally, and it opens with the fact a reader most needs and is least likely to guess:

One of the two is delivered and the other is not. saphan-gateway is part of the machine payload — every delivery route carries it, so it is already on any machine you installed. saphan-oauth is carried by no release artifact at all, and that is stated here rather than dressed up as a procedure: there is no route this document can give you for obtaining it today. What each one serves, what it needs from you, and the order they must be started in are below.

The record projection needs neither of them. saphan server is a verb of the saphan CLI, so the read-only MCP projection and the /get bootstrap route in Fleet machines, from a running server are available on any machine an install has already put saphan on. Start it with saphan server start; Getting started and MCP server describe what it serves.

saphan-gateway — the versioned client API

It is a separate, stateless process serving the client contract beneath /v1, /metrics, and the console screens built from the shipped UI bundle. It links a record store because the engine door it calls is the engine, and it owns no database, decision cache or session of its own.

The human ceremony lives in Gateway, and it is not duplicated here: "Signing in (the human act)" is the numbered runbook — 1. set the credential once per workspace · 2. restart the gateway if it was already running · 3. log in from a browser · 4. log in from a shell · 5. what is open without a session · 6. when it refuses. "Start, check, and stop" is the lifecycle (start [--detach], stop, status, the pidfile, the .addr file and what each status verdict means), and "Startup refusals" is the table to read when it will not come up. Its configuration is Configuration [gateway].

⚠ The verb is start, not serve. serve existed for one round and is gone; the binary refuses it by name and prints the replacement.

saphan-oauth — the authorization server

It is this product's OAuth 2.1 authorization server: /authorize, /token, /jwks, both discovery documents, and the seat and client administration panel. It states this product's identity from configuration and from nowhere else — no code path derives its issuer from a request header — and it refuses to start rather than starting with something wrong.

The human ceremony lives in Configuration, numbered end to end: 13.1 decide how the connection is encrypted · 13.2 write the settings · 13.3 create the first signing key · 13.4 start it · 13.5 check it from outside · 13.6 when it refuses to start. Identity and OAuth is the operator's map for the running server, and Issuer enrolment is the separate human-gated act of teaching the engine to honour the tokens it issues.

⚠ A signing key is never created automatically — saphan-oauth key mint is a human act, and a server with no key does not start. That is deliberate, and §13.3 says why.

⚠ The verb is serve, not start — the opposite of the gateway's. The two daemons were written a release apart and their verb surfaces have not been reconciled; check the document for the one you are starting rather than reasoning from the other.