Creating Clusters
Clusters are named logical groups of hosts, including a single host. Groups may overlap; they do not partition the physical machines. Save all your nodes as the default cluster, then add smaller groups when useful. Prefer cluster names over explicit host lists for everyday commands. See Recommended Cluster Setups for one-, two-, four-, and eight-node examples.
Create a cluster
Section titled “Create a cluster”sparkrun cluster create mylab \ --hosts 192.168.11.13,192.168.11.14 \ --default \ -d "My DGX Spark lab"Options
Section titled “Options”| Option | Description |
|---|---|
--hosts / -H | Comma-separated list of host IPs or names |
--default | Make this the default cluster for subsequent commands |
-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
Section titled “Host ordering”The first host of the scheduled placement becomes head; occupancy scheduling can choose a different host from the first saved candidate. Host order still matters for greedy placement. Inspect the plan/status for the actual head.
# Save candidates; scheduling determines the actual headsparkrun cluster create mylab --hosts 192.168.11.13,192.168.11.14SSH user
Section titled “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 dgxuserOr override per-command with --user.
Transfer mode
Section titled “Transfer mode”sparkrun cluster create mylab \ --hosts 192.168.11.13,192.168.11.14 \ --transfer-mode delegatedControls 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
Section titled “Cache directory”sparkrun cluster create mylab \ --hosts 192.168.11.13,192.168.11.14 \ --cache-dir /data/hf-cacheOverride 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
Section titled “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.15sparkrun cluster update mylab --user newusersparkrun cluster update mylab -d "Updated description"
# Add or remove individual hostssparkrun cluster update mylab --add-host 192.168.11.16sparkrun cluster update mylab --remove-host 192.168.11.14Set as default
Section titled “Set as default”sparkrun cluster set-default mylabWhen a default cluster is set, commands like sparkrun run use it automatically without needing --cluster or --hosts.
Next steps
Section titled “Next steps”After creating a cluster, set up SSH access for multi-node inference.
Placement, state, and cache policy
Section titled “Placement, state, and cache policy”Hardware inventory, per-host executor destinations, and live reservations determine placement. Ordinary workloads reserve accelerators exclusively; a low engine memory fraction does not automatically permit co-location. See Schedulers. Workload metadata is shared across direct and daemon calls, while daemon operation history is separate. Missing observations are not proof of idle capacity. Cluster model validation/selection/provider settings and runtime cache cleanup are covered in Model Cache Management.