Run a GPU Worker

Prepare NVIDIA video decode libraries and run a Worker with a CUDA-enabled execution host.

Run a Worker on a machine with an NVIDIA GPU. A GPU Worker is an ordinary Worker started from a CUDA-enabled build of the CLI, which can decode H.264 video, such as the camera recordings behind the frames Table, on the GPU with NVDEC. You start it the same way as any other Worker, and you can put it in a pool such as gpu.

Prerequisites

You can run your own Workers: you have a workload for them and, if you want one, a Worker Pool.
A Linux machine with an H.264-capable NVIDIA GPU and a compatible driver.

Availability

GPU execution requires a CUDA-enabled spiral-host binary. A public distribution of that binary is in development. The standard CLI installation does not enable CUDA. This guide applies when you already have a compatible CUDA-enabled execution host.

Install the video decode libraries

To decode H.264 on the GPU, the machine also needs:

NVDEC (libnvcuvid.so.1). On Ubuntu, install the decode package that matches the driver branch, for example libnvidia-decode-595-server for the 595 server driver.
NVIDIA Performance Primitives (NPP) 13 or later: libnppc, libnppidei, libnppicc, libnppial, and libnppig, all with the same major version.

In a container, allocate GPUs with NVIDIA Container Toolkit, and set the video capability in the image before you create the container. Without it, the container gets the GPU but not the decode library:

ENV NVIDIA_DRIVER_CAPABILITIES=compute,utility,video

Check that NVDEC loads where the Worker will run:

python3 -c 'import ctypes; ctypes.CDLL("libnvcuvid.so.1"); print("NVDEC runtime available")'

This check loads the library only. It does not check NPP or codec support.

Start the Worker

Set the workload's credentials and start the Worker from the CUDA build:

export SPIRAL_CLIENT_ID=work_01GHI
export SPIRAL_PRIVATE_KEY="$(cat work_01GHI.jwk)"
spiral-host worker start --project demo --pool gpu

The Worker registers like any other and claims the same Tasks.

Register the GPU

A Worker does not detect GPUs, and by default it registers none. You can declare them with these variables:

Variable	Value
`SPIRAL_WORKER_GPU_COUNT`	The number of available GPUs, as a positive integer.
`SPIRAL_WORKER_GPU_MEMORY_BYTES`	GPU memory for each Attempt, as a positive integer in bytes.
`SPIRAL_WORKER_GPU_MODEL`	Optional. The GPU model, such as `NVIDIA L4`, shown with the Worker's metrics.

Set the count and the memory together; if you set only one, the Worker does not start. Spiral does not check the values against the hardware.

Registering a GPU changes which Tasks the Worker claims. A Worker that registers a GPU claims only Tasks that require one, and a Worker without one claims only Tasks that do not. Every built-in Task asks for a CPU resource profile, so today a Worker with a registered GPU would claim none of them. Leave the variables unset unless you run Tasks that require a GPU.

Troubleshooting

Problem	Cause	Fix
The Worker exits at start	Only one of `SPIRAL_WORKER_GPU_COUNT` and `SPIRAL_WORKER_GPU_MEMORY_BYTES` is set.	Set both, or neither.
The Worker runs but claims no Tasks	It registered a GPU, and no waiting Task requires one.	Unset the GPU variables and restart the Worker.
The NVDEC check fails	The decode package is missing, or the container lacks the `video` capability.	Install the decode package that matches the driver, or set `NVIDIA_DRIVER_CAPABILITIES` and recreate the container.

Where next: inspect the Tasks and Workers of the pool.

Found a problem? Edit this page or report an issue.

PrerequisitesCopy Anchor Link

AvailabilityCopy Anchor Link

Install the video decode librariesCopy Anchor Link

Start the WorkerCopy Anchor Link