The admin service
The admin service is the out-of-band control and diagnostic plane of a
cell. It is defined as much by what it does not hold as by what it does: it
owns no database, holds no primary state, and attaches read-only. The
separation is deliberate, the tool you reach for when things are broken must not
itself be able to break state.
Feeds: Platform Foundation.
What it owns
Nothing, by design. admin is a control and diagnostics surface that:
- attaches read-only to the other services and aggregates their state;
- offers out-of-band control and diagnostics that do not depend on the data path being healthy;
- is the safe place to look when the primary path is degraded.
Sub-modules (public names)
| Sub-module | What it does |
|---|---|
| Admin API | The out-of-band control and diagnostic API |
| Health | Read-only health aggregation across services |
| Tasks | Diagnostic and control tasks (no primary state) |
APIs and surfaces
The admin service exposes an HTTP surface only: a loopback clear port for
local diagnostics and a mutual-TLS port requiring a client certificate for
out-of-band control. It advertises no data-plane surface and runs no gRPC
listener. External access, where permitted at all, is through the
node front door. See the
Ports & protocols reference.
Workers
Diagnostic and health-aggregation tasks only. Because admin holds no primary
state, it has no reconciliation, replication, or lifecycle workers.
Owns nothing, attaches read-only
Figure: admin (outlined, holds no state) attaches read-only (dotted
edges) to the state-owning services. There is no edge from admin that writes
state anywhere. Ceiling: the diagram shows the ownership boundary; a few control
actions are write operations dispatched through the owning service's own API,
never a direct write to its store.
Table equivalent
| From | Relationship | To | Writes state? |
|---|---|---|---|
| admin | read-only attach | system | No |
| admin | read-only attach | security | No |
| admin | read-only attach | storage | No |
| admin | read-only attach | data | No |
What it actually exposes
The surfaces are chosen to be the ones that stay useful precisely when the primary path is not.
| Surface | What it answers |
|---|---|
| Diagnostics | The general out-of-band diagnostic surface |
| Database health | Per logical database, over the same set it attaches read-only |
| Attestation health | Whether cells are attesting what they are actually running |
| Migrations | Schema migration state, which is exactly what you need when a cell will not come up cleanly |
| Join authorizations | The signed authorizations that let a cell join a node |
Its background work is the same shape: a fabric health agent, a radio health agent, a crypto poll, a metrics publisher, and meter and cost flushes. Watching and forwarding, not owning.
One list, not two
A detail worth keeping, because it is the class of defect that makes a health surface lie. The set of logical databases the admin service monitors is imported from the set it attaches, so the two cannot diverge.
The alternative would be a health monitor listing databases the read-only watcher never attached, reporting on stores it is not looking at. A health view that covers a store nobody attached is worse than one that admits a gap, because it reports health for something it cannot see.
Why it depends on security, and nothing else
The admin service declares exactly one dependency: security, because security publishes the runtime TLS material admin consumes.
It deliberately does not depend on the system service. Its startup is kept unblocked, and it attaches its read-only database handles dynamically rather than requiring them at boot.
That is the whole design in one line: the diagnostic plane must be able to come up when the thing you are diagnosing did not. A control plane that cannot start until the platform is healthy is a control plane you cannot use in an incident.
The separation, stated plainly
Two properties together make this a genuine out-of-band plane rather than an admin console with extra permissions:
- It owns no database and writes nothing. The read-only policy is a property of how it attaches, not a convention its callers observe.
- It can start without the rest of the platform being well. One dependency, dynamic attachment, no primary state to recover.
Ask of any platform's admin tooling: can it start when the platform cannot, and can it corrupt anything if it is compromised? Here the answers are yes and no, and both are structural.
In the deployment matrix
admin runs identically everywhere. Single-cell, it aggregates that one cell's
state. Multi-cell, it aggregates read-only across the cells under a node.
Sovereign / air-gapped, it is fully functional locally and, because it depends on
nothing external, it is exactly the plane that still works when connectivity does
not.
Related topics
- Platform services overview, the two structural facts, including "admin owns nothing."
- Observability & metering, the health and metering views admin aggregates.
- Ports & protocols reference.