Registries

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

Default registries

sparkrun includes the following registries out of the box:

Registry	Source	Visible	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	Avarok-Cybersecurity/atlas-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.

Visible registries appear in sparkrun list and sparkrun search. Hidden registries are still usable by name (e.g., sparkrun run @experimental/my-recipe) or with sparkrun list --all.

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

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 — official recipes appear in sparkrun list and sparkrun search, while experimental ones can be accessed with sparkrun list --all or by name.

@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 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.

Evolving integration

Registry structure and Spark Arena integration are still evolving. We’ll be adjusting based on community feedback — if you have suggestions, open an issue or reach out on the Spark Arena community channels.

View configured registries

sparkrun registry list

Add a registry

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.

# Add without triggering the post-add refresh of all registries
sparkrun registry add https://github.com/myorg/spark-recipes.git --no-update

Note

The repository must contain a .sparkrun/registry.yaml manifest file — see Creating a registry below.

Remove a registry

sparkrun registry remove myteam

Enable/Disable registries

# Disable a registry (keeps config, excludes from searches)
sparkrun registry disable myteam

# Re-enable a disabled registry
sparkrun registry enable myteam

Update registries

sparkrun registry update

Fetches the latest recipes from all enabled remote registries.

List benchmark profiles

# 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

Search across registries

sparkrun search qwen3
sparkrun recipe search llama

Searches by name, model, and description across all enabled registries.

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:

.sparkrun/registry.yaml

registries:
  - name: my-recipes
    subpath: recipes
    description: My custom recipes

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.md

Each YAML recipe file should follow the recipe format.

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:

.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)

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	If false, recipes are hidden from default listings but still usable by name.

Canonical vs short keys

The local ~/.config/sparkrun/registries.yaml uses canonical key names (subpath, tuning_subpath, benchmark_subpath, mods_subpath). Repo manifests support both the canonical names and the shorter aliases listed above (recipes, tuning, benchmarks, mods); when both are present, the canonical key wins.

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:

.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.

Trust model

Recipes can declare shell commands that run before, after, or alongside the serve workload: pre_exec (inside the container), 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 sparkrun prompts before each hook surface runs. Use --trust only when you’ve reviewed the recipe and intend to run its hook content.

URL recipes are never auto-trusted

A recipe fetched from a URL — including @spark-arena/<id> links — always requires confirmation or --trust, regardless of any other setting. Before 0.3.0 these carried no source registry and were treated as local, so their hooks ran with no prompt: a “run this link” code-execution path. Fetching is now further restricted to https:// with a host allowlist, redirect re-validation, and a response size cap.

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-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.

What trust does NOT cover

Trust gates pre_exec / post_exec / post_commands shell content, but not recipe-driven privileged container fields (cap_add, devices, security_opt, privileged, …). Adding a third-party registry implies trusting its recipes’ privileged fields.

See Security model for the full picture.

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

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.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:

sparkrun run @my-team/my-model-vllm -H 192.168.11.13

Recipe discovery order

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

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>.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.