Skip to content

Registries

sparkrun ships with several default registries and supports adding custom ones. Registries are git repositories containing YAML recipe files.

sparkrun includes the following registries out of the box:

RegistrySourceStemlessDescription
@officialspark-arena/recipe-registryYesVetted recipes from Spark Arena. Tested and reviewed for correctness.
@eugreugr/spark-vllm-dockerYesRecipes from the eugr/spark-vllm-docker repository.
@sparkrun-transitionaldbotwinick/sparkrun-recipe-registryYesRecipes originally part of sparkrun’s built-in defaults, now maintained separately.
@experimentalspark-arena/recipe-registryNoExperimental Spark Arena recipes. Less tested or using newer features.
@communityspark-arena/community-recipe-registryNoCommunity-contributed recipes.
@atlasAtlas-Inf/sparkrun-recipesNoOfficial Atlas recipe registry (bundled as a default in sparkrun v0.2.31+). See the Atlas runtime docs for details.
@sparkrun-testingdbotwinick/sparkrun-recipe-registryNoInternal testing registry with recipes, tuning configs, and benchmark profiles.

Stemless means a registry’s recipes are visible without providing an @registry/ stem: they appear in default sparkrun list and sparkrun search results and can be referenced by recipe name alone. Registries with Stemless: No still work while enabled: use a qualified name such as sparkrun run @experimental/my-recipe, list one with sparkrun list @experimental, or include all enabled registries with sparkrun list --all.

Use sparkrun registry list to see all configured registries and their status.

An enabled plugin can contribute registries automatically, including recipes, tuning configurations, benchmark profiles, and mods. These appear in sparkrun registry list with a plugin:<owner> source. Your saved configuration takes precedence; changes such as disabling or trusting a contributed registry persist, and removing one prevents the plugin from adding it back automatically.

Plugin authors can use register_default_registry without cloning repositories or editing user configuration during startup. See Plugin Development: plugin-owned registries for the registration example, stemless access, overrides, and trust rules.

The lil launcher uses the lil catalog for its launch manifests. Sparkrun’s bundled lil plugin translates those manifests into v2 recipes for the B12X vLLM image. It contributes the @lil registry and the lil recipe-format adapter. Plugin loading and its registry.lil capability default on only for alpha; on other channels, enable both:

Terminal window
sparkrun plugins enable lil
sparkrun setup features enable registry.lil
sparkrun registry update lil
sparkrun list @lil
sparkrun show @lil/<Entry>
sparkrun run @lil/<Entry>
sparkrun export recipe @lil/<Entry> --realize --cluster mylab --save realized.yaml

Choose an entry from the catalog and inspect its hardware requirements before launch. Listing reads cached metadata without model-network lookups; loading can resolve additional checkpoint facts. The adapter’s conditional settings select supported hardware configurations during placement. See realized exports to save resolved settings and pinned references.

Plugins can register other foreign recipe formats through Other recipe formats.

Spark Arena is the community recipe hub for DGX Spark. Vetted recipes are published to the @official registry; experimental recipes go to @experimental. Both are included by default. The official registry is stemless; the experimental registry requires an @experimental/ stem for recipe references. Use sparkrun list @experimental or sparkrun list --all to discover its recipes.

The special @spark-arena/<UUID> shortcut pulls recipes directly from the Spark Arena leaderboard. This lets you quickly test or reproduce results for any entry on the leaderboard:

Terminal window
# Run a Spark Arena leaderboard recipe by its ID
sparkrun run @spark-arena/<recipe-id>
# Inspect with VRAM estimation
sparkrun show @spark-arena/<recipe-id>
# Save a local copy for customization
sparkrun export recipe @spark-arena/<recipe-id> --save my-recipe.yaml

Visit spark-arena.com to browse the full catalog, view benchmark results, and copy recipe links.

Terminal window
sparkrun registry list
Terminal window
sparkrun registry add https://github.com/myorg/spark-recipes.git

The repository will be cloned using a sparse checkout for efficiency. If recipes live in a subdirectory, they will be discovered automatically. By default registry add also fetches all enabled registries afterwards to refresh the cache.

Terminal window
# Add without triggering the post-add refresh of all registries
sparkrun registry add https://github.com/myorg/spark-recipes.git --no-update
Terminal window
sparkrun registry remove myteam
Terminal window
# Disable a registry (keeps config, excludes from searches)
sparkrun registry disable myteam
# Re-enable a disabled registry
sparkrun registry enable myteam
Terminal window
sparkrun registry update

Fetches the latest recipes from all enabled remote registries.

Terminal window
# List all available benchmark profiles across registries
sparkrun registry list-benchmark-profiles
# Show details of a specific benchmark profile
sparkrun registry show-benchmark-profile deepseek-r1-distill-671b
Terminal window
sparkrun search qwen3
sparkrun recipe search llama

Searches by name, model, and description across enabled stemless registries. Add --all to include non-stemless registries, or name one explicitly with sparkrun search @experimental/qwen3.

A recipe registry is a git repository containing YAML recipe files and a .sparkrun/registry.yaml manifest that tells sparkrun where to find them.

Example manifest format:

.sparkrun/registry.yaml
registries:
- name: my-recipes
subpath: recipes
description: My custom recipes
my-recipes/
├── .sparkrun/
│ └── registry.yaml # ← manifest (required for auto-discovery)
├── recipes/
│ ├── my-model-vllm.yaml
│ ├── my-model-sglang.yaml
│ └── experimental-model.yaml
├── tuning/ # optional — Triton kernel tuning configs
│ └── sglang/
│ └── ...
├── benchmarking/ # optional — benchmark profiles
│ └── my-model-bench.yaml
├── mods/ # optional — shared mods referenced from recipes (run.sh + supporting files)
│ └── my-mod/
│ ├── run.sh
│ └── ...
└── README.md

Each YAML recipe file should follow the recipe format.

When a user runs sparkrun registry add <url>, sparkrun clones the repository and reads .sparkrun/registry.yaml to discover all registries declared in the repo. Without this file, auto-discovery will fail.

A manifest declares one or more registries under the registries key:

.sparkrun/registry.yaml
registries:
- name: my-team
description: My team's curated recipes
recipes: recipes # path to recipe YAML files
tuning: tuning # path to tuning configs (optional)
benchmarks: benchmarking # path to benchmark profiles (optional)
mods: mods # path to shared mods (optional)
FieldRequiredDefaultDescription
nameyes—Unique registry name. Used in @name/recipe syntax and CLI commands.
descriptionno""Human-readable description shown in sparkrun registry list.
recipesno"recipes"Subdirectory containing recipe YAML files.
tuningno""Subdirectory containing Triton kernel tuning configs.
benchmarksno""Subdirectory containing benchmark profile YAML files.
modsno""Subdirectory containing shared mods (run.sh + supporting files) referenced from recipes’ mods: field. Conventionally mods when present.
enablednotrueWhether the registry is active on first add.
visiblenotrueControls stemless access. If false, recipes require an @name/ stem and are omitted from default listings; use --all or name the registry explicitly to list them.

The configuration key remains visible; sparkrun registry list labels this setting Stemless. It is separate from enabled.

A single git repository can host multiple registries. This is useful when you want to separate stable recipes from experimental ones:

.sparkrun/registry.yaml
registries:
- name: my-team
description: Production-ready recipes
recipes: stable/recipes
tuning: stable/tuning
benchmarks: stable/benchmarking
- name: my-team-experimental
description: Experimental recipes — use at your own risk
recipes: experimental/recipes
visible: false

sparkrun uses a sparse checkout, so only the declared subdirectories are fetched — the rest of the repo is not downloaded.

Recipes can declare shell commands that run before, after, or alongside the serve workload: pre_exec and mods (inside the container before serving), post_exec (inside the container after a health check), and post_commands (on the control machine). To prevent a third-party registry from silently running arbitrary commands, sparkrun gates these hooks with a per-recipe trust flag.

A recipe is trusted (hooks run without prompting) when:

  • the user passed --trust on the CLI;
  • the recipe was loaded from a local path (no source_registry);
  • the recipe came from a registry marked trusted: true in your registries.yaml — every registry sparkrun ships by default is first-party and ships trusted; or
  • you marked its registry trusted explicitly (below).

A registry you add yourself is untrusted until you say otherwise.

Otherwise interactive launches ask once for all hooks and mods, before preparation or replacement; non-interactive launches require explicit authorization. Dry runs only report the required trust. Use --trust after reviewing the recipe’s commands and execution settings. See Security & Trust.

If you operate a registry yourself and don’t want a prompt on every run, mark it trusted once:

Terminal window
sparkrun registry trust my-team
sparkrun registry untrust my-team # revoke
# or trust at the point of adding
sparkrun registry add https://github.com/myorg/spark-recipes.git --trust

This makes every recipe from that registry auto-run its hooks. Only do it for registries whose contents you control or review.

See Security model for the full picture.

Certain name prefixes (sparkrun, official, arena, spark-arena, etc.) are reserved for repositories hosted under approved GitHub organizations. If you use a reserved prefix from an unauthorized URL, sparkrun registry add will reject it.

Choose a name that identifies your team or project (e.g., my-team, acme-llm, lab-recipes).

Once you’ve pushed your repository with a .sparkrun/registry.yaml manifest, anyone can add it:

Terminal window
sparkrun registry add https://github.com/myorg/spark-recipes.git

sparkrun clones the repo, reads the manifest, and registers all declared entries. Your recipes then appear in sparkrun list and can be run by name:

Terminal window
sparkrun run @my-team/my-model-vllm --cluster mylab
  1. @spark-arena/ shortcut — @spark-arena/UUID expands to a Spark Arena URL
  2. URL — if the argument is an HTTP/HTTPS URL, the recipe is fetched directly and cached
  3. @registry/recipe-name scoped lookup — disambiguate recipes across registries
  4. Exact/relative file path — if the argument is a path to an existing file
  5. Current working directory — sparkrun scans .yaml/.yml files in the CWD that are valid recipes
  6. Registry search — flat name lookup in configured registries, then recursive glob

Two rules govern step 6, and both exist to make ambiguity mean something real:

  • Flat beats nested, per registry. A flat <recipes>/<name>.yaml wins and suppresses that registry’s recursive scan — but never another registry’s.
  • .yaml beats a same-stem .yml, in the same directory. They are one recipe spelled two ways. The same stem in different subdirectories stays two distinct recipes.

So when sparkrun reports an ambiguous name, there genuinely are several recipes. The error lists them path-qualified; pick one with the @registry/<relpath> form.

The same rules apply to benchmark profiles, tuning configs, and mods, so listing and lookup can never disagree.

Filenames are matched with or without .yaml/.yml extensions.

Installing a managed plugin trusts its Python source; it does not grant trust to recipes in registries it declares. Registry trust remains a separate authorization decision. Catalog imports retain their external-source provenance even when staged at a local path. See Security.