Registries
sparkrun ships with several default registries and supports adding custom ones. Registries are git repositories containing YAML recipe files.
Default registries
Section titled “Default registries”sparkrun includes the following registries out of the box:
| Registry | Source | Stemless | Description |
|---|---|---|---|
@official | spark-arena/recipe-registry | Yes | Vetted recipes from Spark Arena. Tested and reviewed for correctness. |
@eugr | eugr/spark-vllm-docker | Yes | Recipes from the eugr/spark-vllm-docker repository. |
@sparkrun-transitional | dbotwinick/sparkrun-recipe-registry | Yes | Recipes originally part of sparkrun’s built-in defaults, now maintained separately. |
@experimental | spark-arena/recipe-registry | No | Experimental Spark Arena recipes. Less tested or using newer features. |
@community | spark-arena/community-recipe-registry | No | Community-contributed recipes. |
@atlas | Atlas-Inf/sparkrun-recipes | No | Official Atlas recipe registry (bundled as a default in sparkrun v0.2.31+). See the Atlas runtime docs for details. |
@sparkrun-testing | dbotwinick/sparkrun-recipe-registry | No | Internal 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.
Plugin-owned registries
Section titled “Plugin-owned registries”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 catalog
Section titled “The lil catalog”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:
sparkrun plugins enable lilsparkrun setup features enable registry.lilsparkrun registry update lilsparkrun list @lilsparkrun show @lil/<Entry>sparkrun run @lil/<Entry>sparkrun export recipe @lil/<Entry> --realize --cluster mylab --save realized.yamlChoose 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
Section titled “Spark Arena”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.
@spark-arena/ shortcut
Section titled “@spark-arena/ shortcut”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:
# Run a Spark Arena leaderboard recipe by its IDsparkrun run @spark-arena/<recipe-id>
# Inspect with VRAM estimationsparkrun show @spark-arena/<recipe-id>
# Save a local copy for customizationsparkrun export recipe @spark-arena/<recipe-id> --save my-recipe.yamlVisit spark-arena.com to browse the full catalog, view benchmark results, and copy recipe links.
View configured registries
Section titled “View configured registries”sparkrun registry listAdd a registry
Section titled “Add a registry”sparkrun registry add https://github.com/myorg/spark-recipes.gitThe 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.
# Add without triggering the post-add refresh of all registriessparkrun registry add https://github.com/myorg/spark-recipes.git --no-updateRemove a registry
Section titled “Remove a registry”sparkrun registry remove myteamEnable/Disable registries
Section titled “Enable/Disable registries”# Disable a registry (keeps config, excludes from searches)sparkrun registry disable myteam
# Re-enable a disabled registrysparkrun registry enable myteamUpdate registries
Section titled “Update registries”sparkrun registry updateFetches the latest recipes from all enabled remote registries.
List benchmark profiles
Section titled “List benchmark profiles”# List all available benchmark profiles across registriessparkrun registry list-benchmark-profiles
# Show details of a specific benchmark profilesparkrun registry show-benchmark-profile deepseek-r1-distill-671bSearch across registries
Section titled “Search across registries”sparkrun search qwen3sparkrun recipe search llamaSearches 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.
Creating a registry
Section titled “Creating a registry”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:
registries: - name: my-recipes subpath: recipes description: My custom recipesRepository layout
Section titled “Repository layout”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.mdEach YAML recipe file should follow the recipe format.
The .sparkrun/registry.yaml manifest
Section titled “The .sparkrun/registry.yaml manifest”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:
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)Manifest fields
Section titled “Manifest fields”| Field | Required | Default | Description |
|---|---|---|---|
name | yes | — | Unique registry name. Used in @name/recipe syntax and CLI commands. |
description | no | "" | Human-readable description shown in sparkrun registry list. |
recipes | no | "recipes" | Subdirectory containing recipe YAML files. |
tuning | no | "" | Subdirectory containing Triton kernel tuning configs. |
benchmarks | no | "" | Subdirectory containing benchmark profile YAML files. |
mods | no | "" | Subdirectory containing shared mods (run.sh + supporting files) referenced from recipes’ mods: field. Conventionally mods when present. |
enabled | no | true | Whether the registry is active on first add. |
visible | no | true | Controls 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.
Multiple registries per repo
Section titled “Multiple registries per repo”A single git repository can host multiple registries. This is useful when you want to separate stable recipes from experimental ones:
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: falsesparkrun uses a sparse checkout, so only the declared subdirectories are fetched — the rest of the repo is not downloaded.
Trust model
Section titled “Trust model”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
--truston the CLI; - the recipe was loaded from a local path (no
source_registry); - the recipe came from a registry marked
trusted: truein yourregistries.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.
Trusting a registry
Section titled “Trusting a registry”If you operate a registry yourself and don’t want a prompt on every run, mark it trusted once:
sparkrun registry trust my-teamsparkrun registry untrust my-team # revoke
# or trust at the point of addingsparkrun registry add https://github.com/myorg/spark-recipes.git --trustThis 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.
Reserved name prefixes
Section titled “Reserved name prefixes”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).
Example: adding your registry
Section titled “Example: adding your registry”Once you’ve pushed your repository with a .sparkrun/registry.yaml manifest, anyone can add it:
sparkrun registry add https://github.com/myorg/spark-recipes.gitsparkrun clones the repo, reads the manifest, and registers all declared entries. Your recipes then appear in sparkrun list and can be run by name:
sparkrun run @my-team/my-model-vllm --cluster mylabRecipe discovery order
Section titled “Recipe discovery order”@spark-arena/shortcut —@spark-arena/UUIDexpands to a Spark Arena URL- URL — if the argument is an HTTP/HTTPS URL, the recipe is fetched directly and cached
@registry/recipe-namescoped lookup — disambiguate recipes across registries- Exact/relative file path — if the argument is a path to an existing file
- Current working directory — sparkrun scans
.yaml/.ymlfiles in the CWD that are valid recipes - Registry search — flat name lookup in configured registries, then recursive glob
Resolution rules
Section titled “Resolution rules”Two rules govern step 6, and both exist to make ambiguity mean something real:
- Flat beats nested, per registry. A flat
<recipes>/<name>.yamlwins and suppresses that registry’s recursive scan — but never another registry’s. .yamlbeats 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.
Plugin-contributed registries
Section titled “Plugin-contributed registries”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.