Install a host

One command turns an Ubuntu Server 24.04 machine into a Community host. It checks the machine, installs the session services, then shows a code to pair the machine with your account. Nothing to copy from the console. About 5 minutes.

Before you start

• A machine that meets the Provider requirements: Ubuntu Server 24.04 on the machine itself, the HWE kernel (Linux 6.12 or newer), virtualization and IOMMU on in the firmware.
• A terminal on the machine, as a user who can run sudo.
• A provider account with a verified email address, as an owner or admin of your organization.

1. Run the command on the machine

curl -fsSL https://nodelodge.com/host | sudo bash

Type it as shown. It asks for your sudo password once, then:

1. Checks the release key. The start script carries the Node Lodge release key and compares it with the key published in DNS, apart from this site (see The release key). If they differ, nothing runs.
2. Checks the installer. It downloads install.sh and its signature and checks the signature with that key. If the check fails, nothing runs.
3. Checks the machine. Each requirement gets a line: ok, WARN or MISSING, with the fix. When something only you can change is missing (the firmware, the kernel, the system), it stops before changing anything.
4. Checks the release. The agent, the session daemon and their service files come in one signed file, checked against the same key before it is unpacked. Cloud Hypervisor and the registry mirror are checked against fixed SHA-256 digests.
5. Installs. System packages, Node.js 22, the accounts nl-vmd, nl-mirror and nl-agent, the release under /opt/nodelodge, and four services that start at boot.
6. Shows a code. The agent generates its key on the machine and prepares to pair. Only the public half of the key leaves the machine.

The terminal then shows:

  To pair this machine, open nodelodge.com/pair on any device signed in to Node Lodge
  and enter the code K7QX-M2PD, or scan:

  (QR code)

  The code expires in 10 minutes. Waiting for approval...

2. Enter the code

On any device signed in to Node Lodge, your phone included:

1. Open nodelodge.com/pair and enter the code, or scan the QR code: it opens the same page with the code filled in.
2. Check the machine: GPU and VRAM, CPU, memory, system, and the address and country its request came from. If you did not start this install yourself, select Decline.
3. Name the machine. The hostname is proposed; renters see the name, so avoid personal details.
4. Select Pair this machine.

The machine finishes on its own: it receives its credentials, pairs, and runs the self-test. The console opens its page, awaiting review.

A code works once, for 10 minutes. Only an owner or admin of the organization can approve it, from a signed-in browser.

What runs on the machine

No service listens on a network port. The agent connects out to Node Lodge over HTTPS.

Check the host

sudo /opt/nodelodge/install.sh --check

Reads the machine, the services and the pairing, runs the self-test, and changes nothing. It ends with host ready, or with the list of what to fix.

Update and roll back

sudo /opt/nodelodge/install.sh --update
sudo /opt/nodelodge/install.sh --rollback

--update installs the newest release, signed by a release key already pinned on the machine. Releases only move forward: the machine refuses any release older than the newest it has installed, and any key retired by a later release, whatever the server sends. The previous release stays on disk, and --rollback returns to it; the next --update moves forward again. Sessions keep running through both.

Running the command again is safe: what is already right stays as it is, and a machine already paired is not paired again.

Options

Add options after sudo bash -s --:

curl -fsSL https://nodelodge.com/host | sudo bash -s -- --skip-dns-check

Without a browser near the machine

For automation, or a machine where nobody can open the console: in Setup, under No browser at hand, name the machine and select Generate pairing code. The console shows a command that carries the code to the installer on its standard input, never in the arguments of a process. The code works once and expires after 15 minutes.

GPUs

Rented GPUs belong to the VMs: bound to vfio-pci, with no NVIDIA driver on the host. Reserve them as described in Provider requirements, then check the host again.

The release key

The start script checks the installer against this public key, the one that signs every Node Lodge release:

MCowBQYDK2VwAyEAMpBEdmKh+jNxfzcsprbjpeoESLOYNWJtfH1Eq3eGekw=

The same key is published in DNS, in a DNSSEC-signed zone, apart from the console and this site. The start script reads it before anything runs; to read it yourself:

dig +short TXT _host-release-key.nodelodge.com

The answer is the key above, in quotes. During a key change, it lists both keys. Once installed, the machine checks every update against the keys it pinned.

To read the start script before you run it, download it with its signature and check it with the key above:

curl -fsSL -o host.sh https://nodelodge.com/host
curl -fsSL -o host.sh.sig https://nodelodge.com/host.sig
printf '%s\n' '-----BEGIN PUBLIC KEY-----' 'MCowBQYDK2VwAyEAMpBEdmKh+jNxfzcsprbjpeoESLOYNWJtfH1Eq3eGekw=' '-----END PUBLIC KEY-----' > release-key.pem
base64 -d host.sh.sig > host.sh.raw
{ printf 'nl-host-bootstrap\0'; cat host.sh; } > host.sh.msg
openssl pkeyutl -verify -pubin -inkey release-key.pem -rawin -in host.sh.msg -sigfile host.sh.raw
sudo bash host.sh

Troubleshooting