Skip to main content
A new cloud server can connect itself as a worker: no shell on it, no approval. In Settings → Workers → Enrollment tokens, enter the worker’s label, choose what it connects as (Worker or Remote, as in Enroll a machine with a token) and create a token. Then choose Cloud server, and:
  • a cloud: AWS, Google Cloud, Azure, DigitalOcean, Hetzner, Vultr, Akamai, Scaleway or OVHcloud;
  • a format: cloud-init, to paste where the cloud’s console creates a server, or a Terraform or OpenTofu file that creates the server for you;
  • a region and a size. The cloud bills you for the server, not r5d.
Settings lists a few common regions and sizes of each cloud, but any region and size the cloud offers works, x86 or Arm: choose another in the cloud’s console, or with the file’s region and size variables (-var size=…). The page writes the file around the token, in your browser: the token never goes back to r5d. Copy or download the file before you leave the page, since the token is shown only once. Every server runs Ubuntu 24.04. To run the worker in a container instead, choose Container, which writes the container files around the token the same way (Run a worker in a container). For a virtual machine that stops when you aren’t using it, choose boat.dev (Run a worker on a boat.dev sandbox).

What the server does on first boot

  1. It installs git, Docker (Ubuntu’s docker.io, with Buildx and Compose), and Node.js 24 with npm from NodeSource’s signed package repository.
  2. It adds the user r5d, with passwordless sudo and the docker group: the server is the worker’s, so agents install what they need and build and run containers there.
  3. It installs Bun, at the version r5d pins and checked against its published checksum, into /home/r5d/.bun.
  4. As r5d, it installs the CLIs at your environment’s version, with the same command Settings → Workers shows, then enrolls them with the token (r5d-worker auth --enroll).
  5. It starts the worker as the systemd service r5d-worker, which starts again on every boot. The service is the one in Run the worker as a service: the worker’s life vest resumes it when a signal stops it and starts it again when it exits or hangs, so you don’t have to log in to the server to bring it back. systemd starts it again after any exit but a refused sign-in (exit code 78), and gives the worker 90 seconds to stop.
The worker connects out to r5d, so the server needs no inbound port. It shows under Your workers a few minutes after the server starts. On the server, /var/log/cloud-init-output.log shows the first boot and journalctl -u r5d-worker the worker.

The token

The token works once, within an hour of its creation, and only for its label. Create the server within that hour; one that boots later can’t enroll, so create a new token and file. An open token can be revoked in Settings → Workers. The token is in the server’s user data, which the cloud keeps, and with Terraform or OpenTofu in main.tf (and, with some clouds’ providers, in the state file beside it). Once the server has enrolled, it is spent: it can’t enroll anything else. On the server, the first boot keeps it in a file only root can read and deletes that file once the server is enrolled, and nothing prints it to a log. The cloud’s metadata service still serves the user data to the server, where agents, who have sudo, can read it: by then the token is spent.

SSH

The server accepts no SSH password logins: its first boot sets cloud-init’s ssh_pwauth: false. Some clouds, such as Hetzner, DigitalOcean and Vultr, give a server created without an SSH key a root password, which they email to you or show in their console; that password works only in the cloud’s web console. To log in with SSH, give the server your public key when you create it: in the SSH key field of the cloud’s console, or in main.tf with the provider’s key setting below. SSH also needs port 22 open where the cloud’s firewall blocks inbound connections, as on AWS and Azure; the worker itself needs no inbound port.

cloud-init

Create a server in the cloud’s console with Ubuntu 24.04 and the region and size you chose, and paste the file as its user data: The file is the same for every cloud. In outline, with the values Settings fills in as placeholders:
A remote’s file starts r5d-worker start --remote. cloud-init schema --config-file user-data.yaml checks a file before you use it.

Terraform and OpenTofu

The file is one main.tf for Terraform or OpenTofu: the provider, the server with what the cloud needs around it (on Azure a resource group of its own with a network and a public address, on Scaleway a public address), and the cloud-init document above as its user data. Its variables: Each provider reads your credentials as its tools do: Save the file as main.tf in an empty directory, then run there, for example on Hetzner:
With Terraform, run terraform init and terraform apply instead. apply shows the plan and asks before it creates anything; -var size=<size> or -var region=<region> changes a choice.

Delete the server

With Terraform or OpenTofu, run tofu destroy (or terraform destroy) in the same directory: it reads the state file apply left there. A server created in the console is deleted there. Then revoke the worker’s sign-in under Settings → CLI & API → Authorized devices, where it is listed with the badge Only and its label, such as Only gpu-server. The worker’s retained work goes with the server’s disk: let agents finish and publish their work first.

When the worker doesn’t connect

Log in to the server, with an SSH key you gave the cloud (SSH) or in the cloud’s web console, and look at:
  • The token was refused (expired, used or revoked): create a new token for the same label, then on the server enroll and start the worker by hand:
  • The cloud refused the size or region: not every region offers every size. Choose another in Settings, or change -var size=….
  • Nothing in the logs: the server may not run cloud-init with this user data. Check that it runs Ubuntu 24.04 and that the file was pasted where the table above says.