uvacompute

node management

contribute your gpu hardware to the uvacompute network. nodes run vms and container jobs for users on the platform.

prerequisites

  • a linux machine with nvidia gpu(s)
  • installed the uva cli
  • authenticated with uva login
  • root/sudo access on the machine

installing a node

1

prepare your system

install nvidia drivers and check system requirements:

sudo uva node prepare

this installs nvidia drivers and verifies iommu support

2

create a registration token

generate a token for node registration:

uva node token create

tokens are single-use and expire after 24 hours

3

install the node

install k3s, kubevirt, and register with uvacompute:

sudo uva node install

you'll be prompted for the registration token from step 2

pausing a node

pausing a node prevents new workloads from being scheduled while allowing existing workloads to complete.

via cli

uva node pause

via web dashboard

  1. go to my nodes
  2. click on your node to expand it
  3. click "pause node"

note: when paused, the node shows as "draining" status. existing vms and jobs will continue running until they complete.

resuming a node

resuming a paused node allows it to accept new workloads again.

via cli

uva node resume

via web dashboard

  1. go to my nodes
  2. click on your paused node to expand it
  3. click "resume node"

uninstalling a node

completely remove uvacompute from your machine.

1

pause and wait for workloads

pause the node and wait for existing workloads to complete:

uva node pause
2

run the uninstall command

remove k3s, kubevirt, and all uvacompute components:

sudo uva node uninstall

this removes k3s, kubevirt, ssh tunnel service, and gpu scripts

node status reference

statusindicatordescription
online●accepting and running workloads
draining◐paused - existing workloads continue, no new workloads
offline○node is unreachable or not running

gpu mode management

nodes with nvidia gpus can switch between container mode (nvidia driver, for jobs) and vm passthrough mode (vfio-pci driver, for gpu vms). must be run on the node.

check current mode

uva node gpu-mode status

switch modes

uva node gpu-mode nvidiauva node gpu-mode vfio

gpu sharing & protection

when your node is in nvidia mode, you can still use your own gpu for local work. uvacompute automatically detects when the gpu is in use and prevents scheduling conflicts.

how it works

the gpu-guardian daemon is installed automatically during node setup. it monitors your gpu device files using linux fanotify and periodic scans:

  • when you start a gpu process (e.g. pytorch, llama.cpp), the guardian detects it within seconds and marks your gpu as busy
  • while the gpu is marked busy, no new gpu jobs will be scheduled on your node
  • when your process finishes, the guardian removes the busy marker and gpu jobs can be scheduled again

gpu mode behavior

  • nvidia mode: gpu-guardian runs automatically. your local gpu usage is detected and protected.
  • vfio mode: gpu-guardian is stopped. the gpu is fully passed through to vms and cannot be accessed by the host.

switching gpu modes with uva node gpu-mode automatically starts or stops the guardian.

note: gpu-guardian only distinguishes between host processes and kubernetes (job) processes. if you are running a local gpu workload, all gpus on the node are marked as busy — even on multi-gpu systems.

additional commands

list your tokens

uva node token list

check node status

uva node status