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 the one-line install, a route from it to the internet. A machine with no such route is installed from a package instead.
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,saphan-server}: the control-plane CLI, the runner-side
agent, the console (which also serves the /setup page a fresh machine is set up through), and
the server that carries the mailbox, the chat integrations and the act authority the console's
passkey prompt talks to. Every delivery route — the one-line install, the deb, the rpm and the
macOS installer — carries those four binaries and nothing else. No package installs a service,
writes a configuration file, or touches ~/.saphan state; identity and configuration are made
later, per user, by explicit verbs (saphan install, saphan config init, saphan ceremony …,
saphan machine … — see Configuration and Security).
Uninstalling a machine install removes what it put there and your state survives
(Uninstall).
2. What runs CENTRALLY? Server surfaces, and they are not all the same kind of thing — Central servers is the whole of it:
| central surface | what it serves | which program | obtained by |
|---|---|---|---|
| record projection | the read-only MCP projection, the record as static pages, and the /get route a fleet machine can install from | saphan server (a verb of the saphan CLI), and the projection service inside saphan-server | part of the machine payload |
| console + client API | the versioned client contract under /v1, /metrics, the console screens, and /setup — the page a machine with no owner is set up through | saphan-gateway — a separate process | part of the machine payload |
| server | the mailbox and chat integrations, and the act authority that verifies a passkey before an act is recorded | saphan-server — a separate process | 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.
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 page in a browser, or saphan install in a terminal | First run: setting the machine up at /setup |
| A machine that is already installed | the same line, run again | Updating a fleet |
| A Linux machine with no route to the internet | a 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 each route carries
Every delivery route — the one-line install, the deb, the rpm, the macOS installer and the
/get route of saphan server — carries the same four binaries for the same three release
targets. The product's own build refuses a release in which any route disagrees with the others
about either list.
What this section does not cover
⚠ 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. Coming back after a restart is a separate act
with its own verb, saphan service; no package registers a
service for you.