Creating Clusters

Clusters are named groups of DGX Spark hosts. Save your hosts once and reference them by name in every command.

Tip

New to sparkrun? Run sparkrun setup wizard for a guided walkthrough that creates your cluster, sets up SSH, configures networking, and more — all in one step.

Create a cluster

sparkrun cluster create mylab \
  --hosts 192.168.11.13,192.168.11.14 \
  -d "My DGX Spark lab"

Options

Option	Description
--hosts / -H	Comma-separated list of host IPs or names
-d / --description	Human-readable description
--user	SSH user for connecting to hosts
--cache-dir	Override HuggingFace cache directory for this cluster
--transfer-mode	Resource distribution mode: auto (default), local, push, delegated
--transfer-interface	Network interface for high-speed transfers between cluster hosts

Host ordering

The first host in a cluster definition is used as the head node for multi-node jobs. Order the remaining hosts however you like — they become workers.

# 192.168.11.13 is the head node
sparkrun cluster create mylab --hosts 192.168.11.13,192.168.11.14

SSH user

By default, sparkrun uses your current OS user for SSH. Set a per-cluster user:

sparkrun cluster create mylab \
  --hosts 192.168.11.13,192.168.11.14 \
  --user dgxuser

Or override per-command with --user.

Transfer mode

sparkrun cluster create mylab \
  --hosts 192.168.11.13,192.168.11.14 \
  --transfer-mode delegated

Controls how container images and models are distributed to cluster hosts. Options: auto (default), local, push, delegated. See Networking for details on each mode.

Cache directory

sparkrun cluster create mylab \
  --hosts 192.168.11.13,192.168.11.14 \
  --cache-dir /data/hf-cache

Override the HuggingFace cache directory for this cluster. By default, sparkrun uses the standard HuggingFace cache resolution (see Troubleshooting for the full resolution order).

Update a cluster

Modify hosts, description, or SSH user of an existing cluster:

sparkrun cluster update mylab --hosts 192.168.11.13,192.168.11.14,192.168.11.15
sparkrun cluster update mylab --user newuser
sparkrun cluster update mylab -d "Updated description"

# Add or remove individual hosts
sparkrun cluster update mylab --add-host 192.168.11.16
sparkrun cluster update mylab --remove-host 192.168.11.14

Set as default

sparkrun cluster set-default mylab

When a default cluster is set, commands like sparkrun run use it automatically without needing --cluster or --hosts.

Next steps

After creating a cluster, set up SSH access for multi-node inference.