Central servers: saphan-server, saphan-gateway and saphan-oauth
What the central server programs are, what each one serves, which of them a delivery route carries, and what each needs from you.
The rest of this section puts the machine payload on a machine. This page is about what serves a fleet centrally, and it opens with the fact a reader most needs and is least likely to guess:
Two of the three are delivered and the third is not. saphan-server and saphan-gateway are
part of the machine payload — every delivery route carries them, so they are 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 site can give you for obtaining
it today.
On a fresh machine the one-line install starts the first two for you, and the setup page
offers to register them with the machine's supervisor so they come back after a restart
(saphan service). Started by hand, each is its own verb:
and each answers stop and status the same way.
saphan-server — the server
It carries the mailbox and the chat integrations, the act authority — the private socket the
console's passkey prompt talks to, which verifies a person's passkey before an act is recorded —
and the read-only projection of the record. ⚠ Without it the console reads and every act refuses
by name, so a machine with a console and no saphan-server looks finished and is not.
saphan server — a verb of the saphan CLI — runs the same read-only projection on its own: the
MCP projection, the record as static pages, and the /get route a fleet machine can install from
(Fleet machines). Start it with saphan server start;
MCP server describes what it serves. saphan serverd is a former command: it
refuses and prints the saphan-server line to use instead.
saphan-gateway — the console and the versioned client API
It is a separate, stateless process serving the client contract beneath /v1, /metrics, the
console screens, and /setup while the machine has no owner. It owns no database, decision cache
or session of its own.
It listens on loopback by default. ⚠ A non-loopback --listen requires the full mutual-TLS set
— --tls-cert, --tls-key and --client-ca together — because without it the process would serve
in the clear. The models, terminals and runs the console starts are started by the operator's
launcher (saphan-agent launcher), which saphan service install registers.
The human steps live in Gateway, and they are not duplicated
here: signing in (set the credential once per workspace, restart the gateway if it was already
running, log in from a browser or a shell, what is open without a session, and what to do when it
refuses), the start/check/stop lifecycle, and the table of startup refusals. Its configuration is
the [gateway] section of Configuration.
⚠ The verb is start, not serve. The binary refuses serve 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 steps live in Starting the authorization server for the first time: decide how the connection is encrypted, write the settings, create the first signing key, start it, check it from outside, and what to do when it refuses to start. Identity is the operator's map for the running server, and Trusting an issuer 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.
⚠ The verb is serve, not start — the opposite of the gateway's. Check the page for the one
you are starting rather than reasoning from the other.