---
title: Registries
description: Configure custom recipe registries for sharing and discovering recipes.
---

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 | Description |
|---|---|
| `@official` | Vetted recipes from [Spark Arena](https://spark-arena.com). These have been tested and reviewed for correctness. |
| `@eugr` | Recipes from the [eugr](https://github.com/eugr) repository. Available by default. |
| `@sparkrun-transitional` | Recipes that were originally part of sparkrun's built-in defaults, now maintained as a separate registry. |
| `@experimental` | Experimental recipes from Spark Arena. These may be less tested or use newer features. Hidden from default listings but usable by name. |

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

## Spark Arena

[Spark Arena](https://spark-arena.com) 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:

```bash
# 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 show @spark-arena/<recipe-id> --save my-recipe.yaml
```

Visit [spark-arena.com](https://spark-arena.com) to browse the full catalog, view benchmark results, and copy recipe links.

:::note[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

```bash
sparkrun registry list
```

## Add a registry

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

:::note
The repository must contain a `.sparkrun/registry.yaml` manifest file — see [Creating a registry](#creating-a-registry) below.
:::

## Remove a registry

```bash
sparkrun registry remove myteam
```

## Enable/Disable registries

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

# Re-enable a disabled registry
sparkrun registry enable myteam
```

## Update registries

```bash
sparkrun registry update
```

Fetches the latest recipes from all enabled remote registries.

## List benchmark profiles

```bash
# 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

```bash
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:
```yaml
# .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
└── README.md
```

Each YAML recipe file should follow the [recipe format](/recipes/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:

```yaml
# .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)
```

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

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

```yaml
# .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.

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

```bash
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:

```bash
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

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