Install Fuzzball on an NVIDIA DGX Spark
This guide covers the NVIDIA DGX Spark specifics for bringing up a single-host Fuzzball cluster with GPU passthrough. It builds on the platform-agnostic Docker Compose tab of the Deployment guide — install, DNS, login, lifecycle, upgrading, and troubleshooting all live there. This page covers only what is different on the DGX Spark.
The DGX Spark is a Grace Blackwell GB10 personal supercomputer: linux/arm64, 128 GB of unified
LPDDR5x, an integrated Blackwell GPU, and DGX OS (Ubuntu-derived). Because every Fuzzball image is
published as a multi-arch manifest, no custom builds are required — the operator just runs the
standard CLI. Once finished, you’ll have an orchestrator, web UI, auth (Keycloak), persistent state
(PostgreSQL), and a substrate node that schedules GPU workflows onto the Blackwell GPU.
The GPU-enabled substrate image (selected with --gpu) passes the GPU through to workflow containers
via the NVIDIA Container Toolkit on the host.
DGX OS or an Ubuntu-derived distribution shipping the NVIDIA Blackwell driver. Confirm with:
$ nvidia-smiExpected output: at least one GPU listed with a non-empty driver version.
Docker Engine with the compose plugin (preinstalled on DGX OS).
Install the Fuzzball CLI (use the arm64 .deb
package), then deploy with --gpu to select the GPU substrate image for the DGX Spark’s Blackwell
GPU:
$ fuzzball cluster docker-compose deploy \
--gpu \
--update-etc-hosts \
--upSee Deploy for what the flags do and DNS resolution for domain options, then Log in with the CLI.
$ fuzzball node list --available-resources
NODE ID | HOSTNAME | CPU TYPE | AVAILABLE CORES | AVAILABLE MEMORY (GB) | AVAILABLE DEVICES | RUNNING JOBS | CLUSTER
172.21.0.5/7333 | substrate-localnode-1 | cpu/arm64 | 20 | 127.9 | nvidia.com/gpu:1 | 0 | local-devIf AVAILABLE DEVICES shows nvidia.com/gpu:N, the substrate-side GPU plumbing is working.
For registry authentication (pull access denied), certificate trust, and inspecting the stack
directly, see the Docker Compose troubleshooting
section. DGX-specific issues:
nvidia.com/gpu doesn’t appear in AVAILABLE DEVICES
The substrate couldn’t see the GPU. On the host, confirm the Blackwell driver is loaded and
nvidia-smi lists the GPU, then re-run the deploy.
High memory pressure or OOM during workflow runs
The DGX Spark’s 128 GB is unified between CPU and GPU — a large GPU-resident model competes with the rest of the stack. The base Fuzzball stack rests at ~2-3 GB. Leave at least 4-8 GB headroom for the control plane when sizing GPU workflow memory budgets.
An LLM entry (vLLM / GPT-OSS) aborts at start: “less than desired GPU memory utilization”
The vLLM-based catalog entries default GpuMemoryUtilization to 0.9, asking for 90% of
total GPU memory to be free at startup. That suits a dedicated GPU, but the Spark’s memory
is unified with the host, so 90% is rarely free enough and vLLM exits with:
ValueError: Free memory on device cuda:0 (.../121.69 GiB) on startup is less than desired GPU
memory utilization (0.9, 109.52 GiB). Decrease GPU memory utilization or reduce GPU memory
used by other processes.Lower the fraction to leave room for the host — GpuMemoryUtilization=0.7 is a good starting
point on a 128 GB Spark:
$ fuzzball workflow catalog start "GPT-OSS 20B" --values GpuMemoryUtilization=0.7Lifecycle, upgrading, and teardown are the same as any Docker Compose deployment:
- Lifecycle commands — start, stop, status, logs
- Upgrading — bump to a newer image tag
- Tear down — stop or remove the deployment
- Beyond a single host — attach remote substrate nodes and production hardening
For GPU scheduling details (requesting nvidia.com/gpu in a workflow, GPU health monitoring), see
GPUs.