What you need
- A Linux server with systemd, on amd64 (x86_64) or arm64 (aarch64). Any other OS or CPU fails before anything is changed.
- SSH access as
root, or as a user that can run every command as root without a prompt. The installer writes under/etcand/var/liband runssystemctl. - The server must reach the control plane’s agent port (9443 by default) outbound, and pull the agent image from the registry. The control plane must reach the server’s SSH port.
- Your control plane address as the server sees it. The CLI defaults to the host of
--api-urlwith port 9443. Pass--control-plane-addrif that is not reachable from the server.
Add the server
- Dashboard
- CLI
- API
Open Nodes, then Add node, then Connect over SSH. Enter the host and port. The Verify server step reads the server’s host keys without sending any credential. Compare a fingerprint with the server, confirm it, then enter the username and a key or password. The wizard shows each stage and a live log tail.
Host key handling
Credentials only go to a server whose host key you have seen.POST /api/v1/nodes/ssh-provision/preflight with {"host": "...", "port": 22} reads the host keys and aborts the handshake right after key exchange, so no username, password or key is sent. It returns each key type and its SHA256 fingerprint. Compare one with the server:
insecure_skip_host_key_check is rejected with 400. Skipping the check is recorded in the audit log as node_ssh_provision.host_key_skipped.
What it installs
- Connects and detects the OS, CPU architecture, Docker and systemd. This step changes nothing on the server.
- Installs Docker with
curl -fsSL https://get.docker.com | shandsystemctl enable --now dockerwhen Docker is missing. - Creates
/var/lib/levelrail-agent-data(root only), writes/etc/levelrail-agent.envwith mode0600(it holds the join token) and writes/etc/systemd/system/levelrail-agent.service. The unit runs the agent image as a container. - Runs
systemctl daemon-reload && systemctl enable --now levelrail-agent, waits two seconds and checks the service isactive. If it is not, the last lines ofjournalctl -u levelrail-agentbecome the failure reason.
When it fails
To undo an adoption, remove the node from Nodes, then on the server run
systemctl disable --now levelrail-agent and delete the three paths above.
Not yet verified on a real host
- No run of this flow against a real VPS, home server or Raspberry Pi is recorded yet.
- Servers where the SSH user is not root and needs
sudoare not covered. Useroot. - Docker installed from a distribution package instead of
get.docker.comis detected, but the combinations have not been tested.