Skip to main content
One command turns a GPU machine into a Runcrate host. It asks for a registration token from your dashboard, installs the Runcrate agent and hands the machine’s GPUs to it. The agent only runs software Runcrate signed, needs no inbound port, and keeps every customer inside a VM with no route into your network. What runs on your machine lists every file it adds and everything it can see. On a machine that meets the requirements below, the install takes about 35 seconds. If the IOMMU is off, add one reboot (see The reboot).

​
Requirements

  • Bare metal, x86_64. Not a virtual machine: the GPUs are passed through to customer VMs, which needs the real hardware.
  • Ubuntu 22.04, Ubuntu 24.04 or Debian 12.
  • NVIDIA GPUs: datacenter cards (A100, H100, H200, B200, L40S, RTX 6000 and others) or GeForce RTX 30, 40 and 50 series.
  • Virtualization (VT-x or AMD-V) and IOMMU (VT-d or AMD-Vi) turned on in the BIOS. If the kernel has the IOMMU off, the installer offers to turn it on for you.
  • Outbound HTTPS. No inbound ports; NAT is fine.
  • Fast local disk for VM disks, 100 GB or more free. The data directory must be new or empty: the agent marks it as its own and never shares it with your files.
  • No NVIDIA driver is needed on the host. If one is installed, the installer reads each GPU’s name, memory and ID from it first. Stop anything using the GPUs before you install.

​
Install a machine

1

Create an install command

On Hosts, choose Add a machine and Create install command. You get the command and a registration token. The token works for 30 days, or until you revoke it under Install tokens, and registers as many machines as you like until then, so one token can do a whole cluster.
2

Run it on the machine

When the installer asks for the registration token, paste it and press Enter. The input is hidden. The token never goes on the command line, where every user of the machine could read it in ps.
3

Watch it come online

The Hosts page follows the machine through Registered, Image checked, First heartbeat, GPU check and Online. The GPU check runs in a throwaway VM: a memory test over nearly all of each GPU’s memory, a matrix multiply checked against the CPU, and disk, internet and network isolation checks.
4

List the GPUs

An online machine earns nothing until its GPUs are listed. See Listings and tiers.
Every step of the installer checks before it changes anything, so running the same command again is safe. A machine that is already registered isn’t asked for the token again.

​
Options

Pass options after sh -s --:
To see every option on the machine:

​
Unattended installs

For scripts and fleet tools, put the token in a file only root can read and pass that file. First save the token. Run this, paste the token and press Enter. Like the installer, it hides what you paste:
Then install:
The installer refuses a token file that isn’t owned by root or that anyone else can read. There is no --token option: the installer refuses it, because the token would show in ps.

​
The reboot

GPU passthrough needs the IOMMU. If the kernel has it off, the installer stops and shows the words it would add to the kernel command line, GRUB_CMDLINE_LINUX_DEFAULT:
When you answer yes (or pass --yes), it writes them to 90-runcrate-host.cfg in /etc/default/grub.d/, runs update-grub and reboots 10 seconds later. When the machine is back, run the same install command again and paste the token again (the machine registers only once the IOMMU is on). With --yes and --token-file, run the same line again after the reboot.
That is the only reboot the install needs. If you’d rather add the words yourself, answer no, add them to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, run update-grub, reboot and run the command again. Uninstalling removes what the installer added.

​
What the installer does

  1. Checks the OS, CPU virtualization, the GPUs and the IOMMU.
  2. Installs QEMU/KVM, OVMF, nftables, genisoimage and iperf3 (and perftest when InfiniBand is present).
  3. Creates the unprivileged runcrate-vm user and group. Each customer VM runs as its own user, so one VM can’t reach another’s disk, sockets or process.
  4. Downloads the agent and checks its signature against Runcrate’s release key. It refuses to install anything unsigned.
  5. Takes the GPUs off the host: stops NVIDIA’s persistence daemon and Fabric Manager if they run, and moves each GPU (with the other functions of its card, such as HDMI audio) to vfio-pci.
  6. Registers the machine with your token. The credential it gets back is stored in /etc/runcrate-host/credential, readable by root only.
  7. Starts two services: runcrate-host-gpus (binds the GPUs at boot) and runcrate-host (the agent).