Writing Recipes
Start from an existing recipe
Section titled “Start from an existing recipe”Start from a recipe for the same runtime, using include: for a small variation
or exporting a copy for independent edits. Prefer runtime plus supported
defaults and omit command; add a command only for unusual unmapped flags. Sparkrun will see any recipes in the current directory and can check and run them.
For more complex recipes involving mods, tunings, or benchmarks, it is recommended to first review the Sparkrun security model so you can be aware of important limitations and caveats, and then set up your own recipe registry.
# See what's availablesparkrun list
# Show a recipe's full configurationsparkrun show qwen3-1.7b-vllmSee recipe inheritance,
conditional overrides, and
realized exports for reuse and
hardware-specific settings. Each runtime reference
lists its generated flags and defaults keys.
Step by step
Section titled “Step by step”- Set
modelto the HuggingFace model ID you want to serve - Set
container— see Runtimes Overview for maintained images and latest tags. - Set
runtimeto the engine you’re targeting (vllm,sglang,llama-cpp, etc.). While sparkrun can auto-detect the runtime from the command prefix, explicitly setting it is preferred for clarity and to avoid surprises if the heuristics evolve. - Tune
defaults— start withgpu_memory_utilization: 0.8andmax_model_len: 32768. For vLLM, you can instead usemax_model_len: autoto fit the context length to available GPU memory. Adjust after confirming the model loads. - Validate:
sparkrun recipe validate your-recipe.yaml - Test:
sparkrun run your-recipe.yaml --dry-run
Example: vLLM recipe
Section titled “Example: vLLM recipe”Use runtime: vllm for either backend. With
defaults.distributed_executor_backend omitted or set to mp, Sparkrun selects
native distributed/mp (vllm-distributed); set it to ray for Ray orchestration.
Sparkrun generates the vllm serve command from the runtime and defaults. See
vLLM backend selection.
model: my-org/my-modelruntime: vllmcontainer: scitrera/dgx-spark-vllm:0.16.0-t5
metadata: description: My custom model maintainer: user@example.com
defaults: port: 8000 host: 0.0.0.0 tensor_parallel: 1 gpu_memory_utilization: 0.8 max_model_len: 32768 # or auto for vLLMWith max_model_len: auto, vLLM chooses the largest context length that fits
within the GPU memory budget, up to the model’s supported maximum. See
vLLM’s --max-model-len reference.
- Check the Runtimes Overview to verify you are using the correct or latest container images and runtime options for DGX Spark.
- Use
--dry-runliberally. It shows the exact Docker commands without executing anything. sparkrun show <recipe>displays rendered defaults plus VRAM estimation — use it to sanity-check before launching.- For models that barely fit in VRAM, lower
max_model_lenfirst. KV cache scales with sequence length. tensor_parallelon DGX Spark maps 1:1 to node count.--tp 2means 2 hosts, each contributing 1 GPU.- GGUF recipes should set
max_nodes: 1unless using the experimental RPC multi-node backend.
Sharing recipes
Section titled “Sharing recipes”Create a git repository with your YAML files and a .sparkrun/registry.yaml manifest:
registries: - name: my-team description: My team's recipes for DGX Spark recipes: recipesThen anyone can add your registry:
sparkrun registry add https://github.com/myorg/spark-recipes.gitSee Registries — Creating a registry for the full manifest format, including optional tuning and benchmark paths.