registry

Provides complete reference for managing sparkrun recipe registries, browsing and searching recipes, managing benchmark profiles, validating recipes, and understanding the recipe file format for NVIDIA DGX Spark inference workloads.

<Use_When>

• User wants to add, remove, enable, disable, or update recipe registries
• User wants to browse or search for available recipes
• User wants to create or edit a recipe YAML file
• User wants to validate a recipe or check VRAM requirements
• User wants to browse or inspect benchmark profiles
• User asks about recipe format or fields </Use_When>

<Do_Not_Use_When>

• User wants to run, stop, or monitor workloads -- use the run skill instead
• User wants to install sparkrun or set up clusters -- use the setup skill instead </Do_Not_Use_When>

Registry Commands

# List configured registries (enabled only by default)
sparkrun registry list
sparkrun registry list --show-disabled
sparkrun registry list --only-show-visible

# Add registries from a git repo's .sparkrun/registry.yaml manifest
sparkrun registry add <git_url>

# Remove a registry
sparkrun registry remove <name>

# Enable a disabled registry
sparkrun registry enable <name>

# Disable a registry (recipes will not appear in searches)
sparkrun registry disable <name>

# Update all enabled registries from git (fetches latest recipes)
sparkrun registry update

# Update a specific registry
sparkrun registry update <name>

# Update sparkrun + registries in one command
sparkrun update

Browsing Recipes

# List all recipes across all registries (no filter)
sparkrun list

# List with filters
sparkrun list --all                         # include hidden registry recipes
sparkrun list --registry <name>             # filter by registry
sparkrun list --runtime vllm                # filter by runtime (vllm, sglang, llama-cpp)
sparkrun list <query>                       # filter by name

# Search for recipes by name, model, runtime, or description (contains-match)
sparkrun recipe search <query>
sparkrun recipe search <query> --registry <name> --runtime sglang

# Inspect a specific known recipe (by exact name or file path)
sparkrun recipe show <recipe> [--tp N]

# Export a normalized recipe
sparkrun recipe export <recipe>
sparkrun recipe export <recipe> --json
sparkrun recipe export <recipe> --save out.yaml

Use sparkrun recipe search as the first attempt when looking for a particular recipe. Use sparkrun recipe show when given a specific recipe name or file -- it may not appear in search results.

Recipe names support @registry/name syntax for explicit registry selection (e.g. @spark-arena/qwen3-1.7b-vllm).

Benchmark Profiles

# List available benchmark profiles across registries
sparkrun registry list-benchmark-profiles
sparkrun registry list-benchmark-profiles --registry <name>
sparkrun registry list-benchmark-profiles --all    # include hidden registries

# Show detailed benchmark profile information
sparkrun registry show-benchmark-profile <name>

Validating Recipes

# Check a recipe for issues
sparkrun recipe validate <recipe>

# Estimate VRAM usage with overrides
sparkrun recipe vram <recipe> [--tp N] [--max-model-len 32768] [--gpu-mem 0.9]

Recipe File Format

Recipes are YAML files defining an inference workload:

model: org/model-name                  # HuggingFace model ID (required)
runtime: vllm | sglang | llama-cpp     # Inference runtime (required)
container: registry/image:tag          # Docker image (required)
min_nodes: 1                           # Minimum hosts needed
max_nodes: 4                           # Maximum hosts (optional)
model_revision: abc123                 # Pin to specific HF revision (optional)

metadata:
  description: Human-readable description
  maintainer: name <email>
  model_params: 7B
  model_dtype: fp16
  category: general                    # Recipe category

defaults:
  port: 8000
  host: 0.0.0.0
  tensor_parallel: 2
  pipeline_parallel: 1
  gpu_memory_utilization: 0.9
  max_model_len: 32768
  served_model_name: my-model
  tokenizer_path: org/base-model       # Required for GGUF models on SGLang

# Optional: explicit command template (overrides auto-generation)
command: |
  python3 -m vllm.entrypoints.openai.api_server \
      --model {model} \
      --tensor-parallel-size {tensor_parallel} \
      --port {port}

# Optional: environment variables passed to the container
env:
  NCCL_DEBUG: INFO

# Optional: post-launch hooks
post_exec:                             # Commands to run inside the head container
  - "echo 'Model loaded'"
post_commands:                         # Commands to run on the control machine
  - "curl http://{head_ip}:{port}/v1/models"
stop_after_post: false                 # Stop workload after post hooks (default: false)

Key fields:

• {placeholder} in command: templates are substituted from defaults + CLI overrides
• model_revision pins downloads to a specific HuggingFace commit/tag
• tokenizer_path is required for GGUF models on SGLang (points to base non-GGUF model)
• min_nodes / max_nodes control cluster size validation
• Shell variable references like ${HF_TOKEN} in env: are expanded from the control machine's environment
• post_exec and post_commands run after the server is healthy (port listening + /v1/models check)
• pipeline_parallel enables pipeline parallelism (total nodes = TP * PP)

<Tool_Usage> All sparkrun commands are executed via the Bash tool. No MCP tools are required. </Tool_Usage>

<Important_Notes>

• Run sparkrun registry update or sparkrun update periodically to get the latest community recipes
• Use sparkrun recipe validate before publishing custom recipes
• Use sparkrun recipe vram to check if a model fits on DGX Spark before trying to run it
• When creating GGUF + SGLang recipes, always set tokenizer_path in defaults
• Custom command templates should include all relevant {placeholder} references to pick up defaults and CLI overrides
• Registries are cached at ~/.cache/sparkrun/registries/ and updated with sparkrun registry update
• sparkrun ships with built-in recipes; additional registries point to any git repo containing .yaml recipe files
• Use sparkrun registry list-benchmark-profiles to discover available benchmark profiles from registries
• Recipe names support @registry/name syntax for explicit registry selection
• Use sparkrun recipe export to get a normalized view of a recipe (useful for debugging) </Important_Notes>

Task: {{ARGUMENTS}}