Worker nodes

Agents run on elastic worker pools that we operate — and you can also connect your own machines as worker nodes. An agent you place on one of your nodes runs as a container on hardware you control, while the instance keeps the state, the approvals and the audit trail.

This is the same mechanism our elastic pools use: one control plane, many worker machines.

How nodes connect

Each worker node runs the exohuman-worker service, which:

• connects outbound to the instance — nodes need no inbound ports and are never addressable from the internet;
• registers with a one-time join token, after which it authenticates with its own rotating credential;
• reports its labels (for example gpu=a100), its capacity (how many agents it may host) and a regular heartbeat;
• accepts the agent containers the instance places on it, enforcing per-agent CPU, memory and GPU limits.

Node requirements: Linux x86_64 with Docker Engine, outbound access to your instance, and the drivers and container toolkit for any GPU it carries.

Adding a node (two steps)

1. In Settings → Fleet → Add node, create a worker registration with its name, labels and maximum agents. The instance shows a one-time token and a ready-to-paste docker run command.
2. Run that command on the machine. The node appears as Active within a heartbeat, and you can place agents on it.

No sales call, no manual approval from us: joining your own machines to your own instance is self-service.

Labels and placement

The instance places an agent on a node that:

1. is healthy — a recent heartbeat, not draining or disabled;
2. has free capacity;
3. carries the labels the agent requires.

Label GPU machines by accelerator, for example gpu=l4, gpu=a100 or gpu=h100, and assign GPU-hungry agents to them. Agents without special requirements run on the cloud pools or any general node.

Node states

State	Meaning
Active	Accepting and running agents.
Draining	Finishing current work, accepting nothing new — used before maintenance.
Disabled	Taken out of placement by an operator.
Lost	No heartbeat for 90 seconds. Its leased jobs are re-queued on healthy machines.

Removing a node is the reverse: drain it, wait for running work to finish, disable it and revoke its credential.

Security model

• Node credentials are scoped to the node and rotate automatically; revoking one immediately removes the node from placement.
• Agents on your nodes run under the same per-agent resource limits, approvals and audit logging as agents on cloud pools.
• Your machine stays yours: the worker service cannot run anything that was not placed as an agent by the instance, and node-local data never leaves your network except through the encrypted control-plane channel.

Limitations

• Interactive features such as live output streaming and a shell into an agent work for agents on your nodes through the control-plane relay.
• Placement uses labels and capacity; finer scheduling policies (quotas per GPU type, preemption) are not available yet.
• Worker nodes need outbound connectivity to the instance; fully disconnected operation is not supported.