Initialization & setup
A cell is a whole platform, so bringing one up is not attaching a worker to a cluster. It is standing up a complete, self-sufficient instance with its own identity, its own keys, and its own databases. First boot has to work the same way in a cloud region and on a device that has never seen a network, so the setup flow is local-first, phase-gated, and signature-driven: nothing on the critical path requires a round trip to decide.
What first boot decides
When a cell process starts, it first detects which kind of boot this is and branches accordingly. The state is derived from what the cell can see on disk and in its environment, whether it already holds a cell identity, whether a signed license is present, and whether a join endpoint was configured.
Figure: first-boot state detection. A cell that already holds an identity (green) skips straight to launching services. A fresh cell takes one of three setup branches; the amber, dashed offline branch runs with no network in the loop, verifying a signed bundle against an anchor the cell already holds. Every fresh branch converges on the same phase-gated setup flow before the orchestrator starts the services. Ceiling: the unlicensed "offline free" branch is a build-gated development convenience, a production image requires a signed license or a signed join bundle.
Table equivalent
| Startup state | Trigger | What happens |
|---|---|---|
| Already initialized | Cell identity present on disk | Skip setup; launch the service orchestrator |
| Fresh with license | Signed license present, no identity | Stand up a new node and cell from the license, then run setup |
| Fresh with join endpoint | Join endpoint configured, no identity | Enroll under an existing node (see Joining the fabric), then run setup |
| Fresh + offline | No license, no join endpoint | Licensed air-gap boot verifies a signed bundle locally; the unlicensed free path is development-only, build-gated off in production |
| License upgrade | Identity present, entitlement changed | Re-verify and refresh entitlement without re-provisioning |
The setup flow mints an estate from nothing
Once a fresh branch is chosen, setup runs as a durable, ordered flow, each step recorded so a boot interrupted midway resumes rather than restarting. The flow builds the estate from the license outward, and the ordering is the point: identity and records exist before the keys that sign for them, and the administrator exists before the cell opens for authenticated work.
| Phase | What it establishes |
|---|---|
| Validate | The signed license is verified offline against a build-embedded public key before anything is written |
| Records | The organization, the node, and the cell records are created from the license identity |
| Administrator | The first administrator account is created: the human root of authority for the estate |
| Reference data & profile | Entity types and reference data are seeded, and the cell profile (loadout) is resolved |
| Crypto | Signing and identity keys are provisioned for the organization, node, cell, and administrator, plus the organization's offline join-authorization signing key |
| Activate | Endpoints are populated, an identity snapshot is taken, entitlement is applied, and the Cell Network Fabric is activated |
The acceptance bar is that the cell is usable immediately after initialization, no second configuration pass, and no external control plane to call before the platform will serve work.
A cell can be graded at setup against hardware evidence (TPM, PKCS#11, or a hardware token), and its trust level is written onto the cell record. Where the line sits today: the current path records and grades the evidence schema; verifying a raw TPM quote against an attestation key is a later slice, so a cell with no hardware root grades as software-level trust rather than being refused. Setup does not enforce hardware-attested boot today.
Phase gating: a cell in setup runs only what setup permits
A half-initialized cell must not expose the full platform. System9 enforces this in three independent layers, each failing closed to the most restrictive phase if it cannot determine the current one:
- A pre-auth route allow-list: before authentication exists, only the routes a given phase needs are reachable; everything else is refused.
- A setup gate: authenticated application routes return "unavailable" until the setup flow reports complete.
- Per-service phase gating in the orchestrator: a service can declare the phases it is allowed to run in, and the supervisor refuses to start it outside them.
The known phases run uninitialized → bootstrap → awaiting_admin → complete. A
cell cannot serve general work until it reaches complete, and it cannot be
argued past a phase by reaching an endpoint early, the surface simply is not
there yet.
Cell profiles: general-purpose, dedicated, and tactical
The cell profile chosen at setup decides which services a cell runs and how it behaves on constrained links. There are 13 built-in profiles in two families:
- One general-purpose profile: the default, running the full service set.
- Eight dedicated single-service profiles: each runs the platform's system services plus exactly one domain (storage, data, messaging, security, metrics, compute, or the gateway), for cells that specialize in a service group.
- Four resource-constrained tactical templates: drone/UAV, vehicle, forward operating base, and tactical operations center. These carry the field-specific settings: store-and-forward replication, zeroize triggers, radio bandwidth tiers, power awareness, and a pinned data classification.
The profile is a first-class object on the cell record, not a runtime flag, so "what does this cell run" has one durable answer that survives restart.
Service orchestration at startup
After setup (or immediately, for an already-initialized cell), the service orchestrator brings the platform up:
- Dependency-ordered start: services start in a resolved order and stop in the reverse; a service is not started until its dependencies are ready.
- Readiness gates: each service exposes a readiness check the orchestrator waits on before proceeding.
- Crash recovery with backoff: a crashed service is respawned under a capped exponential backoff and a circuit breaker against restart storms.
- Watchdog reconciliation: a watchdog periodically reconciles desired against actual state and corrects drift.
First boot on the edge
The Edge Agent has the same local-first posture with a much smaller footprint. Two commands matter at first boot:
s9 enrollestablishes the device's delegated identity. The device generates its keypair and persists the private key before any network call (so a partial enrollment cannot strand a device without its own key), builds a certificate-signing request, computes a hardware fingerprint for duplicate-device detection, and submits an enrollment request over its transport stack. See Joining the fabric for what happens on the other end.s9 runstarts the resident daemon. On start it evaluates a consent gate and checks the device's telemetry posture: a device configured to transmit loads its identity, builds its operational transport, and enters the heartbeat loop; a device whose posture is fully air-gapped hands off to an offline mode that runs local model serving and signed, hash-chained journaling with no transport, no heartbeat, and no certificate refresh, the edge equivalent of a cell that never phones home.
The Edge Agent can build a TPM quote and the backend can grade it, but the enroll path does not yet attach one, so a device enrolls at software-level trust today. Hardware-attested enrollment is roadmap, and worth scoping as such.
Across the deployment matrix
| Corner | How first boot behaves |
|---|---|
| Single-cell, cloud | License-driven boot; the development and small-site default |
| Multi-cell, cloud | First cell boots from license and mints the node; further cells enroll under it (see Joining the fabric) |
| Single-cell, air-gapped | Licensed signed-bundle boot; verified locally against a pre-staged anchor, no network |
| Multi-cell, air-gapped | Same offline boot, then cells enroll via signed join bundles delivered over physical media |
Related topics
- Joining the fabric, what a fresh cell does when it enrolls under an existing node instead of standing up a new one.
- The cell model, what the services and databases first boot brings up actually are.
- Deployment topology, cell profiles and the scale axis they serve.
- Edge & fleet management, the transport and fleet machinery the Edge Agent's first boot plugs into.