Servers
What a server is, the two kinds, and the one place that decides which machine a call acts on.
A server is a machine the platform can deploy to. There are two kinds:
| Kind | Reached by | Used by |
|---|---|---|
LOCAL | The Docker socket on the control plane's own machine | Self-hosted installs |
AGENT | One WebSocket the machine opened outwards | Cloud mode, or a second machine on a self-hosted install |
A self-hosted install starts with exactly one server: its own, registered on first boot and
named by LOCAL_SERVER_NAME (default local).
Everything goes through one interface
Every Docker and filesystem operation the platform performs is a ServerDriver call:
interface ServerDriver {
exec(input: ExecInput): Promise<ExecOutput>
execStream(input: ExecInput): AsyncIterable<LogChunk>
writeFile(input: WriteFileInput): Promise<void>
readFile(input: ReadFileInput): Promise<Buffer>
docker(): DockerApi
systemFacts(): Promise<SystemFactsData>
}LocalServerDriver is child_process plus the Docker socket. AgentServerDriver sends the
same calls over a WebSocket the customer's machine opened. Nothing above the driver knows
which one it is talking to — the deploy pipeline, the metrics sampler, and the managed-service
provisioner are one code path.
child_process, dockerode, and node:fs are banned everywhere in the backend outside
src/servers/driver/, and a lint rule enforces it.
Which machine a call acts on
ServerDriverRegistry answers that, in one place:
forServer(id)returns the local driver for aLOCALrow and anAgentServerDriverfor anAGENTone.local()is for work that genuinely belongs to the control plane — the master key, the upload staging directory, the platform's own database backup, the build-log archive — and every caller of it says which.
An agent server with no connected agent throws
It does not fall back to local(). Silently running a customer's deployment
on the control plane is the worst bug this product could have, so an
unreachable server fails loudly instead.
Server status
| Status | Meaning |
|---|---|
ONLINE | Reachable. For an agent server, a socket is open and heartbeats are current. |
OFFLINE | Registered, no agent has connected. |
UNREACHABLE | An agent was connected and has gone quiet past AGENT_OFFLINE_AFTER_SECONDS. |
What a server page shows
Host facts (OS, kernel, architecture, uptime, public IP, virtualisation type), live CPU, memory, disk and network, the container list, and — for an agent server — the agent's version, last-seen time, and whether a socket is open right now. See metrics.
Deleting a server
A DELETE refuses while anything is deployed to it. Orphaning containers on a machine the
portal no longer lists is not something the platform will do quietly.