Skip to content
ColdSnap Docs

Install and set up Sparkrun

For now, set up ColdSnap through the plugin’s DEV_PREVIEW guide. The plugin is not yet bundled with a normal Sparkrun release; bundled integration is coming soon.

The preview provides a Sparkrun environment with the ColdSnap plugin included. Sparkrun handles placement, model and image staging, and the ColdSnap controller tools. Once it is set up, the usual community workflow is materialize locally, then run.

1. Prepare your control node

Section titled “1. Prepare your control node”
  • Install Git, Bash, and uv on a supported control node.
  • Have a working Docker engine available for operations that use containers on the control node. On macOS, this means a Linux Docker engine, such as Docker Desktop.

The DEV_PREVIEW guide covers the full prerequisites. For macOS and controllers with a different CPU architecture from the Spark hosts, also see the plugin’s control-node platform notes.

2. Install the preview

Section titled “2. Install the preview”

Use a Bash shell for these commands; run bash first if your current shell is different:

Terminal window
git clone https://github.com/sparksq/sparkrun-coldsnap-plugin.git
cd sparkrun-coldsnap-plugin
export SPARKRUN_BRANCH=develop-next
source dev.sh

Source dev.sh rather than executing it. It checks out Sparkrun’s develop-next branch, assembles an environment with the live plugin source, installs the development packages, activates the repository’s .venv, and updates the enabled recipe registries. A separate standard Sparkrun installation is not required for this environment.

3. Verify the installation

Section titled “3. Verify the installation”
Terminal window
command -v sparkrun
sparkrun --version
sparkrun coldsnap --help
sparkrun registry list

command -v sparkrun should point inside the plugin checkout’s .venv. The registry list should include coldsnap with plugin:coldsnap as its source.

In each new Bash shell, return to the plugin checkout and activate the preview again:

Terminal window
cd /path/to/sparkrun-coldsnap-plugin
export SPARKRUN_BRANCH=develop-next
source dev.sh

Re-sourcing refreshes the selected Sparkrun branch, development installation, and enabled registries. Run all commands in the community guides from this environment.

If sparkrun coldsnap is missing, check command -v sparkrun and source the setup again. If @coldsnap recipes do not resolve, run sparkrun registry update and inspect sparkrun registry list.

Prepare your hosts

Section titled “Prepare your hosts”
  • Use Sparkrun’s setup documentation to configure your cluster from the preview environment. Save a cluster definition and verify SSH access from your control machine to its hosts.
  • Ensure the target hosts have Docker, NVIDIA driver 580 or newer, and enough disk space for runtime images, model data, and capsules.
  • Make sure you can access the recipe’s model and container repositories.

The published-capsule quickstart uses Qwen 3.8 27B FP8 on vLLM with two compatible DGX Spark GB10 hosts, CUDA 13, and TP2. Use the recipe’s supported hardware and placement; driver version alone does not establish compatibility.

Bundled integration is coming soon

Section titled “Bundled integration is coming soon”

The planned bundled release will let you install Sparkrun through sparkrun.dev and enable ColdSnap without maintaining this development checkout. Until then, use the DEV_PREVIEW setup above.

Choose your next step

Section titled “Choose your next step”