Skip to main content
Use this when you have a server you can SSH into and you do not want to copy a join command onto it yourself. The control plane connects to the machine, installs the node agent as a systemd service and waits for it to enroll. After that the machine is a normal node. To copy the command by hand instead, see Add a node anywhere. For the full multi-node picture see Multi-node.
Not yet verified on a real host. The flow is covered by tests with a fake SSH server, not by a run against a real VPS or home server.

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 /etc and /var/lib and runs systemctl.
  • 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-url with port 9443. Pass --control-plane-addr if that is not reachable from the server.

Add the server

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:
The install then refuses to authenticate to a server that presents any other key. The failure names the expected and the observed fingerprint. A request with neither a fingerprint nor 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

  1. Connects and detects the OS, CPU architecture, Docker and systemd. This step changes nothing on the server.
  2. Installs Docker with curl -fsSL https://get.docker.com | sh and systemctl enable --now docker when Docker is missing.
  3. Creates /var/lib/levelrail-agent-data (root only), writes /etc/levelrail-agent.env with mode 0600 (it holds the join token) and writes /etc/systemd/system/levelrail-agent.service. The unit runs the agent image as a container.
  4. Runs systemctl daemon-reload && systemctl enable --now levelrail-agent, waits two seconds and checks the service is active. If it is not, the last lines of journalctl -u levelrail-agent become the failure reason.
The SSH credential stays in memory for this one run and is never stored or logged. The join token is valid for 30 minutes. Afterwards the agent dials out to the control plane over mTLS, and the node shows up with its preflight checks.

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 sudo are not covered. Use root.
  • Docker installed from a distribution package instead of get.docker.com is detected, but the combinations have not been tested.
Last modified on November 17, 2026