> ## Documentation Index
> Fetch the complete documentation index at: https://runcrate.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Requirements, the one-line install, its options and unattended installs.

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](https://runcrate.ai/docs/hosts/security.md) 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](#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](https://runcrate.ai/dashboard/host), 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**

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl -fsSL https://get.runcrate.ai/host | sudo sh
```

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](https://runcrate.ai/docs/hosts/listings.md).

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 --`:

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl -fsSL https://get.runcrate.ai/host |
  sudo sh -s -- \
  --name rack2-node-01 \
  --site "Rack 2" \
  --gpus 0000:41:00.0,0000:42:00.0
```

| Option | What it does |
| - | - |
| `--name N` | The machine's name in your dashboard. Default: its hostname. |
| `--site S` | Groups machines in one location. Machines on the same site benchmark their bandwidth to each other. |
| `--gpus LIST` | Only these GPUs, as PCI addresses separated by commas (a space after a comma is fine). The rest stay yours. Default: every NVIDIA GPU. List the addresses with `lspci -D -d 10de:`. Read only when the machine registers: to change it later, [add the machine again](https://runcrate.ai/docs/hosts/troubleshooting.md#keep-only-the-gpus-that-passed). |
| `--data-dir D` | Where VM disks live. Default: `/var/lib/runcrate-host`. Needs fast local disk. |
| `--token-file F` | Read the registration token from file F instead of asking. See [Unattended installs](#unattended-installs). |
| `--yes` | Don't ask: turn on the IOMMU and reboot if needed. |

To see every option on the machine:

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl -fsSL https://get.runcrate.ai/host |
  sh -s -- --help
```

## 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:

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
sudo sh -c 'umask 077; stty -echo; read -r token; stty echo; printf "%s\n" "$token" > /root/runcrate-token'
```

Then install:

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl -fsSL https://get.runcrate.ai/host |
  sudo sh -s -- --yes \
  --token-file /root/runcrate-token
```

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`:

```bash wrap theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
# Intel
intel_iommu=on iommu=pt
# AMD
amd_iommu=on iommu=pt
```

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](https://runcrate.ai/docs/hosts/uninstall.md) 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.