NuPaaS DocsServers
A server is one machine in your organization's compute fleet. NuPaaS does not care where it came from — a machine it provisioned for you, a VPS you already owned, or a box under your desk — as long as the agent is installed and the machine reports a heartbeat. The URLs, the API fields and the CLI still say node; the product word is server.
What a server is
Servers belong to an organization, not to a project. Once a server has joined, workloads from any project in that organization can be scheduled onto it. Every server record carries a hostname, a provider, an optional region, a role, a status, and the resources the agent discovered on the machine.
Manage the fleet from /orgs/<org>/infrastructure/nodes. A single node's detail page is at /orgs/<org>/infrastructure/nodes/<nodeSlug>, where the slug is derived from the hostname. Cloud instances that NuPaaS can see through a connector but that are not yet platform servers have their own page at /orgs/<org>/infrastructure/nodes/cloud-instance/<externalId>. A machine NuPaaS ordered on your behalf is an order first and a server later, so it keeps its own page at /orgs/<org>/infrastructure/nodes/managed-server/<orderId> from the moment the order is placed.
Three ways to add one
The three routes differ in who owns the machine and who installs the agent.
| Parameter | Type | Description |
|---|---|---|
| Managed server | provisioned for you | NuPaaS orders the machine, installs the agent, and joins it. Start at /orgs/<org>/infrastructure/nodes/provision. This page is feature-gated: if managed servers are not enabled for your organization it redirects back to the server list. |
| Bring your own machine | you install the agent | Generate a bootstrap token, then run the install command it returns on the machine. The token carries the role and expires; the machine registers itself when the agent first calls home. |
| Adopt a cloud instance | already running | If you have added a cloud connector, NuPaaS lists the instances it can see alongside your servers and can onboard one over SSH using a key you have stored. |
A bootstrap token is minted with a role of either worker or control-plane, defaulting to worker. The response includes an expiresAt timestamp and a ready-to-run installCommand. A token may also carry a maximum use count, so one token can bootstrap a batch of identical machines.
Onboarding
A new server is not usable the moment it appears in the list. It stays in onboarding until three separate things have happened, and the list makes the distinction visible rather than reporting an optimistic ready state:
- the server has registered and been issued its identity,
- the agent has sent a first heartbeat,
- the server's join into the cluster has been confirmed.
Two derived flags on the server row report the last two independently: mesh readiness, meaning the server has network connectivity to the rest of your fleet, and placement readiness, meaning the scheduler will actually put work on it. A server can be reachable and still not be a valid placement target.
Status reference
Server and instance rows share a small vocabulary of statuses. The ones you will see most often:
| Parameter | Type | Description |
|---|---|---|
| pending | status | The record exists; the machine has not completed enrollment. |
| provisioning | status | A server is being created or prepared. |
| bootstrapping | status | The agent is installing and the server is joining. |
| running / active / ready | status | The server is enrolled and healthy. |
| error / failed | status | Enrollment or a lifecycle action did not complete. Retry is available. |
| deleted | status | Removed from the fleet. |
Cloud instances discovered through a connector carry a second, orthogonal field describing their relationship to the platform: none (visible but not adopted), provisioning (adoption in progress), or registered (now a platform server). This is what lets one table show both your unadopted instances and your fleet without conflating them.
What the agent reports
The agent heartbeats on a schedule and attaches a small metrics payload. The detail page renders the most recent one:
| Parameter | Type | Description |
|---|---|---|
| cpuPercent | number | CPU utilisation at the last heartbeat. |
| memPercent | number | Memory utilisation at the last heartbeat. |
| diskPercent | number | Disk utilisation at the last heartbeat. |
| wgPeers | number | How many fleet peers this server currently has a network path to. |
| k3sReady | boolean | Whether the Kubernetes node object reports Ready. |
Alongside the metrics, the server row records the agent version, the operating system and CPU architecture the agent detected, and the timestamp of the last heartbeat. A server whose heartbeat has gone stale keeps its last known values rather than blanking them, so you can see what it looked like when it stopped reporting.
Lifecycle actions
Four actions can be applied to an enrolled server. They are deliberately few — a server is either taking work, not taking work, or gone.
| Parameter | Type | Description |
|---|---|---|
| drain | action | Stop scheduling new work onto the server and move existing workloads off it. The server stays enrolled. |
| resume | action | Undo a drain and allow scheduling again. |
| retry | action | Re-attempt a lifecycle transition that failed, without starting enrollment over. |
| remove | action | Take the server out of the fleet. |
CLI reference
platform node add --role worker # mint a bootstrap token
platform node add --role control-plane
platform node list
platform node drain <nodeId>
platform node remove <nodeId>| Parameter | Type | Description |
|---|---|---|
| --role | string | Role for the bootstrap token: worker or control-plane. Defaults to worker. |
| --org | string | Organization to act against. Defaults to the one in your CLI config. |
| --wait | boolean | On add, poll until the server confirms registration. On by default; pass --wait=false to return immediately. |
| --force | boolean | On remove, skip the confirmation prompt. |
| --json | boolean | Emit machine-readable output. |
Removing a server
Removing a server deletes its record and revokes the credentials it was issued, so the machine can no longer report in. It does not destroy the underlying server — if NuPaaS did not provision the machine, NuPaaS will not delete it. Terminate the server with your provider separately.
Drain first if the server is carrying workloads. Removing a server that still has work on it means that work is rescheduled abruptly rather than moved.
platform node drain <nodeId>
platform node remove <nodeId>