Skip to main content
This page is the short path to a second node. Each step links to the page that holds the detail, so nothing is repeated here. It also says plainly what has and has not been verified, per Feature status.
1

Get a second machine

Pick one of two paths:
2

Set the advertise host before enrolling

Set APP_AGENT_ADVERTISE_HOST on the control plane to the host or IP the remote agent will dial. It defaults to 127.0.0.1. With a mismatch, enrollment succeeds but the node’s session then fails TLS hostname verification on every attempt, and the node stays pending. Details are in multi-node.
3

Enroll and confirm

Mint a join token, run the agent with it, then check that the node reaches online:
A node left pending after its token was spent shows as “Never connected”. Delete it and enroll again with a new token.
4

Place something on it

Pick the node in an app’s create form, run levelrail-cli apps set-node <name> <node-id>, or let auto-placement choose.

​
What has been verified

The join flow was run with two real agent processes, each with its own Docker daemon, against a real control plane binary. Enrollment, cordon, drain with real container relocation, and explicit placement pinning all behaved as documented. That run did not cover:
  • A real WAN or second physical host. Both daemons ran on one machine, so cross-datacenter latency and NAT traversal are untested.
  • The WireGuard mesh between two real hosts. The mesh code is tested against fakes and a single host with a real TUN device. If you turn it on across hosts, open inbound UDP 51820 on the control plane and check levelrail-cli nodes mesh for a handshake per peer. See mesh requirements.
  • Cloud provisioning against real accounts. See what was not tested.

​
If the control plane dies

A container placed on a remote node keeps running and serving, because the agent owns it through its own Docker connection. The agent takes no destructive action on disconnect and retries with exponential backoff until the control plane returns. That node’s services are skipped for reconcile passes until then. Resilience has the measured numbers, and Resilience summary has the overview.

​
Next steps

Multi-node

Enrollment, placement, health, certificates, mesh and the CLI reference.

Node provisioning

Provider credentials, cost and known gaps.

Build node routing

Keep builds off nodes that serve traffic.

Network topology

See nodes, apps and databases on the mesh.
Last modified on October 12, 2026