Fleet

Fleet is the registry of machines that belong to you — the Desktop App on your laptop, a headless node on a box you own, or the nodes of a Kubernetes cluster you configured. It is how the platform knows what compute you have, without you opening a port.

Two kinds of node

Kind	How it appears	persisted
desktop-node	The Desktop App, enrolled with a one-time token.	true
node	A headless node app, enrolled the same way.	true
Cluster nodes	Nodes of your own configured cluster, merged in live and never stored.	false

Cluster nodes are read live from the cluster you configured; the platform's own managed cluster is excluded by a sentinel so you never see infrastructure that is not yours.

Enrolled nodes go offline after five minutes without a heartbeat.

Enrolling a node

Enrollment is outbound-only: the node calls the platform, never the other way round. Nothing needs to be reachable from the internet.

1. Mint a token — Settings → Fleet → Add node, or

   POST /api/fleet/nodes/enrollment-token   { "name": "Mac mini", "kind": "node" }
   → { node, token, expiresInSec }

   The token is shown exactly once and only its SHA-256 is stored. It is single-use and expires in 15 minutes.

2. Hand it to the node — the node app calls the public route with the token as its credential:

   POST /api/fleet/enroll   { "token": "…", "platform": "linux/x64",
                              "version": "1.0.0", "capabilities": ["terminal","workspace"] }
   → { nodeId, secret, node }

   The heartbeat secret is likewise returned exactly once and stored only as a hash.

3. The node reports in — periodically:

   POST /api/fleet/heartbeat   { "nodeId": "…", "secret": "…", "capabilities": [...] }
   → { ok: true, node }

   Last-seen is server-stamped; a node never supplies its own clock.

Every invalid credential path — unknown token, expired token, already-consumed token, unknown node, wrong secret — answers one undifferentiated 401. The response never says which check failed.

Managing nodes

GET    /api/fleet/nodes        list mine (enrolled + live own-cluster)
PATCH  /api/fleet/nodes/:id    { name?, disabled? }
DELETE /api/fleet/nodes/:id    remove the registration

Disabling drains. A disabled node's heartbeats stop being accepted, so it goes quiet immediately rather than at the next sweep. Re-enabling puts it back to offline until its next accepted heartbeat proves it alive. Disabling a node that is still enrolling revokes its unused token.

Everything here is owner-scoped: another account's node id is indistinguishable from one that does not exist.

Capabilities

A node advertises capability tags (up to 16) such as terminal, workspace or docker. These describe what the node can host.

Status. Enrollment, heartbeats, the registry and the Fleet settings page are shipped. Scheduling Tasks onto an enrolled node needs the node worker host, which is on the roadmap — until it lands, Fleet is an accurate inventory of your machines rather than a scheduling target.

Related

• Desktop App · Workers · Kubernetes Deployment