Put your machine to work

A machine you supply runs units of jobs: your own organization’s first, and free to it, then other organizations’. For each unit of theirs it earns its hourly rate, which you set, for the time the unit took, and never more than 80% of the unit’s price (how earnings work). One line installs it, and the dashboard’s Machines page, or unitfabric machines, shows it, sets its rate, pauses it, keeps it to your own jobs or removes it.

What you need

Linux on x86_64, with systemd: Ubuntu 24.04, Debian 13, Fedora 42 and newer, RHEL, Rocky Linux and AlmaLinux 9 and 10, openSUSE Leap 15.6 and Tumbleweed, Arch, or a distribution derived from one of them whose Podman is 4.4 or newer and whose Python is 3.12 or newer. Ubuntu 22.04 (its Podman 3.4 cannot give a container a GPU) and Debian 12 (Podman 4.3, Python 3.11) are refused: use Ubuntu 24.04 or Debian 13. On Arch, upgrade the system first (sudo pacman -Syu): the installer never does.
Windows 11, or Windows 10 21H2 (build 19044) or newer: the installer sets up WSL2 with a Linux distribution of its own, Unitfabric (Ubuntu 24.04), and runs the Linux install inside it. Your own distributions are never used or changed.
An NVIDIA GPU with its driver for GPU work: the driver your distribution packages, 550 or newer, or on Windows the Windows driver, which WSL2 reaches the GPU through. The installer never installs a driver; without one, the machine runs the CPU templates only.
30 GB free under /var/lib at least (a template image is up to 15 GB; 100 GB holds them all), and 8 GB of memory or more: templates ask for 4 to 16 GB.
A way out to the control plane, to ghcr.io, where the template images are, and to our object storage, which the agent reaches by signed links to fetch a unit’s inputs and upload its results, all over HTTPS. The machine opens no port: it asks the control plane for work.

The installer adds the rest: Podman and Python from the distribution, the NVIDIA Container Toolkit from NVIDIA, and the agent. macOS is not supported: it has no CUDA.

Install

Make a supply token on the dashboard’s Machines page, with Add a machine, or with unitfabric supply tokens create <name>. It is shown once, with the lines that install a machine with it and the control plane’s URL filled in, and it enrols machines for a day. On Linux, as a user who may sudo, run one of these two:

curl -fsSL https://unitfabric-site.vercel.app/install.sh | UNITFABRIC_SUPPLY_TOKEN=uf_supply_... sudo -E bash -s -- --control-url <url>

curl -fsSL https://unitfabric-site.vercel.app/install.sh | sudo bash -s -- --control-url <url>

The first carries the token in the environment, and sudo -E hands it to the installer; the second carries none, and the installer asks for it on the terminal without echoing it. On Windows, in an administrator PowerShell, one of these two:

$env:UNITFABRIC_SUPPLY_TOKEN = 'uf_supply_...'; & ([scriptblock]::Create((irm https://unitfabric-site.vercel.app/install.ps1))) -ControlUrl <url>

& ([scriptblock]::Create((irm https://unitfabric-site.vercel.app/install.ps1))) -ControlUrl <url>

The token is never an argument: every user of a machine can read the arguments of its processes (ps), so the installer refuses --token. It uses the token once, to enrol, and never writes it to disk. A line with the token in it stays in your shell’s history, where it can enrol a machine until the token’s day is over.

Both scripts are plain text here, to read before you run them: install.sh and install.ps1.

What the installer does

On Linux, install.sh runs as root and does only what is missing, so running it again is safe:

Checks the machine and prints a line for each check: ok, warn, or FAIL, which stops it before anything changes. --check prints only this report and changes nothing; it needs neither the token nor sudo:
Terminal window
```
curl -fsSL https://unitfabric-site.vercel.app/install.sh | bash -s -- --check --control-url <url>
```
On WSL2, turns systemd on and exits with status 3: restart that distribution from Windows (wsl --terminate <its name>, as the installer’s message says; wsl --terminate Unitfabric for the Windows installer’s own) and run it again. The Windows installer does both itself.
Installs the packages: Podman and Python from the distribution, and the user ids jobs run as: each job runs in a user namespace of its own, from the ranges the installer adds to /etc/subuid and /etc/subgid for the user containers. With a driver loaded, the NVIDIA Container Toolkit and its list of the GPU’s devices (CDI), made again whenever the agent starts, so a new driver needs nothing from you, and where SELinux enforces, the boolean container_use_devices, which lets jobs reach the GPU. And where the distribution packages CRIU 4 with its CUDA plugin (Fedora, openSUSE, Arch), CRIU and NVIDIA’s cuda-checkpoint, with which the agent can checkpoint a running GPU job.
Installs the agent from its package on this site, which the installer checks against its checksum (grid-agent.tar.gz.sha256), into /opt/grid/agent/.venv, with the versions of its dependencies, and of pip and setuptools, it was tested with (a package already installed is not installed again), its configuration in /etc/grid/agent.toml, readable by root alone, and the systemd service grid-agent. Jobs on your machine get no network at all: their inputs are files the agent fetches for them, or text in the unit itself, so nothing a job does reaches the internet from your address.
Enrols the machine with the token, at the rate --rate gives (US dollars an hour) or the one suggested for its GPU, benchmarks the templates it can run (each template’s image is downloaded once, which can take a while; a later run benchmarks again only when the agent changed) and starts the service (a later run restarts it only when something it runs on changed).

It ends with a line such as done: studio, gpu mode on linux, checkpointing off (units restart); manage it on the dashboard's Machines page or with unitfabric machines. To update the agent, run the line you installed with again: a machine already enrolled keeps its enrolment and does not use the token, so one past its day will do. The line without a token still asks for one: give it the one you installed with, which it does not use.

Its options: --name (the hostname by default), --rate, --cpu (the CPU templates only, on a machine with a GPU), --gpu-index N (which GPU, 0 by default), --no-bench (benchmark later: no work comes until it has), --no-start, and --reenrol, which enrols the machine again as a new one (what that changes). To install only a package you have checked yourself, name its SHA-256 with --agent-sha256 <hex>: the installer checks against it instead, and stops if the package it downloads is any other. It exits 0 when done, 1 when a step failed, 2 for a bad argument, a missing sudo or a machine it cannot serve, and 3 when its WSL distribution must restart.

On Windows, install.ps1 installs WSL if it is missing (then restart Windows, and run the line again), imports its own distribution, Unitfabric, from Ubuntu’s image (with no Windows drive mounted in it and no Windows program callable from it), and sizes WSL2’s memory and swap in %UserProfile%\.wslconfig, adding only what the file lacks after keeping a copy of it as it was (.wslconfig.unitfabric-<time>). It runs install.sh inside the distribution, and has Windows start it, and so the agent, whenever Windows starts, or, where Windows does not allow that, when you next sign in. It never stops WSL or your own distributions: the only one it restarts is its own, with wsl --terminate Unitfabric. It takes -Name, -Rate, -MemoryGB and -SwapGB (WSL2’s memory, three quarters of the machine’s by default, and its swap, 8 GB), and -Check, which reports and changes nothing:

& ([scriptblock]::Create((irm https://unitfabric-site.vercel.app/install.ps1))) -Check

A machine that cannot checkpoint, any in WSL2 or without a GPU and one on Linux without CRIU, starts the units of a lease it loses again, and is offered only jobs whose units take at most 10 minutes or that never checkpoint.

What happens next

Pending. The machine appears on the Machines page and in unitfabric machines, with pending among its flags. Until you confirm it, it takes none of your organization’s own jobs, only other organizations’, so a machine enrolled with a token of yours that leaked never sees your work. Confirm it on the Machines page or with unitfabric machines confirm <id>.
Benchmarks. What the machine measured for each template decides what it is offered: the Machines page shows, for each, what your rate earns a unit and, where the rate is too high for the template, below which rate it would be offered its work.
First units. The machine asks the control plane for work. Your organization’s jobs come first, free to it; another organization’s unit goes to the machine that does it at the lowest cost per unit, its rate over the units an hour it was measured at. Another organization’s job comes only once we can check your machine’s work on it, on a machine of ours of the same class: your machine’s GPU class for a job that needs a GPU, a CPU machine for one that does not (trust and verification). So a machine of a GPU class we do not run yet takes your own jobs, and can take other organizations’ jobs that need no GPU; the Machines page says when it is held back.

Every unit it completes for another organization earns: how earnings work. When nothing comes: troubleshooting.