Deployment
What an install is here: which programs a machine gets, which of them run centrally, and which route delivers each.
For whoever puts the product onto machines and answers for them afterwards.
After reading it you can choose a route, install a machine, set the first one up, and verify what landed.
Before you start: a machine you can reach, and — for every route that is delivered today — a Saphan server already running somewhere, or a distribution tree you were given.
Read in this order. An install, end to end first; it is the whole path in one page and it links the rest where each is needed.
What an install is, here
Saphan Studio is a set of programs, and which of them a machine gets depends on what that machine is for. Two questions decide everything below, and they have different answers:
1. What does a FLEET MACHINE receive? The machine payload —
{saphan,saphan-agent,saphan-gateway}: the control-plane CLI, the runner-side agent, and
the console, which serves the /setup wizard a fresh machine is set up through. Every
delivery route carries exactly those and nothing else — the bootstrap, the deb, the rpm and
the macOS installer are ways of moving the same set, each carrying three binaries. No package installs a service, writes a configuration file, or touches ~/.saphan
state; identity and configuration are minted later, per user, by explicit verbs
(saphan config init, saphan ceremony …, saphan machine … — see
Configuration and Security §13). Uninstalling a
machine install removes what it put there and your state survives (Uninstall).
2. What runs CENTRALLY? Three server surfaces, and they are not all the same kind of thing — Central servers: saphan-gateway and saphan-oauth is the whole of it, and it is where a first-time deployment starts:
| central surface | what it serves | which program | obtained by |
|---|---|---|---|
| console + record projection | the owner's /console and every screen under it, the read-only MCP projection, and the /get route the fleet bootstrap in Fleet machines, from a running server downloads from | saphan server — a verb of the saphan CLI, not a separate file | already installed, wherever saphan is |
| client API + console | the versioned client contract under /v1, /metrics, the console screens built from the shipped UI bundle, and /setup — the wizard a machine with no owner is set up through | saphan-gateway — a separate process | installed by every route above (it is part of the machine payload) |
| authorization | OAuth 2.1: /authorize, /token, /jwks, both discovery documents, and the seat/client admin panel | saphan-oauth — a separate process | ⚠ not distributed today (Central servers) |
One server binary is carried by no release artifact: saphan-oauth. Every delivery
route carries the machine payload — the CLI, the agent and the gateway — and none of them
carries the authorization server. Central servers states
that plainly rather than describing an install path that does not exist.
Supported release targets: darwin-arm64, linux-amd64, linux-arm64. There is no
darwin-amd64 and no Windows build.
Pick your path:
| You are installing on | Use | Section |
|---|---|---|
| Any machine | curl -fsSL https://saphan.ai/install.sh | sh — one line, the same on every machine | An install, end to end |
| The first machine, once the binaries are on it | the /setup wizard | First run: setting the machine up at /setup |
| A machine that is already installed | the same line, run again | Updating a fleet |
| A machine with no route to the internet | a signed deb or rpm, carried in — Enterprise | Air-gapped installation |
| A Mac with no route to the internet | the self-extracting installer — Enterprise | The macOS installer |
| VS Code, once a machine is installed | the saphan-code extension | The VS Code extension (saphan-code) |
What this tree builds, and what each route carries
The block below is this document's claim about the shape above, in the form the engine's
own test suite evaluates against the tree. the product reads the binary list out of
cmd/ with os.ReadDir, reads each route's payload out of that route's own source file
(the Makefile variables and its SHA256SUMS glob, install.sh's BINARIES, nfpm's
dst list, the installer stub's copy lines, and the binary list the server's /get route
gates on), and refuses any disagreement by name. The release TARGET list stated above is
checked the same way: RELEASE_TARGETS, the platform gate the /get route matches a
download against, and install.sh's own allowlist must agree with one another. A census
then scans the delivery recipes, the packaging inputs and this chapter for any FURTHER
hand-spelled copy of either list — including that sentence — so a copy living in a file
nobody registered is found rather than remembered. A binary added to cmd/, or a platform
added to the release, turns that suite red until every copy has learned about it, so the
table above cannot quietly fall behind the build the way it did for four release cycles.
What this section does not cover
⚠ Supervision. No route installs a service unit; whether a machine runs the product under an init system is a separate act, and this site has no page for it. ⚠ Backup and restore of the record. ⚠ The authorization server, which no release artifact carries — Central servers says so plainly rather than describing an install path that does not exist.