### Verify Sparkrun Setup

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Runs a series of commands to verify the sparkrun installation and cluster configuration, including showing cluster details, listing available commands, and checking recipe execution.

```bash
sparkrun cluster show <name>
sparkrun list
sparkrun show <recipe> --tp <N>
```

--------------------------------

### Install Sparkrun as a UV Tool with Tab-Completion

Source: https://github.com/scitrera/sparkrun/blob/main/README.md

The `sparkrun setup install` command installs sparkrun as a uv tool, sets up shell tab-completion, and synchronizes registries. This is the primary command for initial setup.

```bash
sparkrun setup install
```

--------------------------------

### Install and Check Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Installs sparkrun using uvx if not already present and checks its version. This command sets up a managed virtual environment and shell tab-completion.

```bash
which sparkrun && sparkrun --version

# If not installed:
uvx sparkrun setup install
```

--------------------------------

### Quick Start: Cluster Setup and Inference

Source: https://github.com/scitrera/sparkrun/blob/main/README.md

Demonstrates the initial setup for sparkrun, including creating and setting a default cluster, configuring passwordless SSH, and running an inference workload with various options like tensor parallelism and on-the-fly overrides.

```bash
# Save your hosts once
sparkrun cluster create mylab --hosts 192.168.11.13,192.168.11.14 -d "My DGX Spark lab"
sparkrun cluster set-default mylab

# Set up passwordless SSH mesh
sparkrun setup ssh

# Run an inference workload
sparkrun run qwen3-1.7b-vllm

# Multi-node tensor parallel (TP maps to node count on DGX Spark)
sparkrun run qwen3-1.7b-vllm --tp 2

# Override settings on the fly
sparkrun run qwen3-1.7b-vllm --port 9000 --gpu-mem 0.8
sparkrun run qwen3-1.7b-vllm --tp 2 -o max_model_len=8192

# GGUF quantized models via llama.cpp
sparkrun run qwen3-1.7b-llama-cpp
```

--------------------------------

### Sparkrun CX-7 Basic Usage Examples

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/networking.mdx

This section provides examples of how to use the `sparkrun setup cx7` command. It shows how to specify hosts directly using their management IPs, use a previously saved cluster configuration, and perform a dry run to preview changes without applying them. These commands automate the detection and configuration of ConnectX-7 interfaces.

```bash
# Specify hosts directly (management IPs) sparkrun setup cx7 --hosts 10.24.11.13,10.24.11.14

# Or use a saved cluster
sparkrun setup cx7 --cluster mylab

# Preview what would be done without making changes
sparkrun setup cx7 --cluster mylab --dry-run
```

--------------------------------

### Install and Update Sparkrun CLI

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/skills/setup/SKILL.md

Installs or updates the sparkrun CLI tool using 'uvx'. It also covers updating sparkrun and its associated registries. Ensure 'uv' is installed first; instructions are provided if needed.

```bash
# Ensure that uv is installed
uv --version

# uv can be installed with (IF NEEDED)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install sparkrun as a CLI tool
uvx sparkrun setup install

# Update to latest version (and registries)
sparkrun setup update

# Update sparkrun only (skip registry sync)
sparkrun setup update --no-update-registries
```

--------------------------------

### Inspect Sparkrun Recipe Details

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Display detailed information about a specific recipe, including a VRAM estimation to check compatibility with DGX Spark's memory before launching.

```bash
sparkrun show nemotron3-nano-30b-nvfp4-vllm
```

--------------------------------

### Install Shell Tab-Completion for Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/README.md

The `sparkrun setup completion` command installs shell tab-completion scripts for sparkrun. This feature enhances usability by providing command and argument suggestions in the terminal.

```bash
sparkrun setup completion
```

--------------------------------

### Install sparkrun with pip

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/installation.mdx

Provides alternative methods for installing sparkrun using pip or uv pip. This method requires manual setup for tab completion.

```bash
pip install sparkrun
# or
uv pip install sparkrun
```

--------------------------------

### Configure CX7 Networking (Optional)

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Sets up static IPs and netplan configuration for ConnectX-7 interfaces on a cluster for high-speed transfers. Requires sudo privileges.

```bash
sparkrun setup cx7 --cluster <name>
```

--------------------------------

### Update Sparkrun and Registries

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Updates sparkrun and its associated registries to the latest available versions.

```bash
sparkrun setup update
```

--------------------------------

### Sparkrun CX-7 Network Setup Commands

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/networking.mdx

These bash commands demonstrate the sequence for setting up CX-7 interfaces using sparkrun. It includes registering the cluster with management IPs, setting up SSH access (which requires passwordless SSH for subsequent steps), and finally configuring the CX-7 interfaces themselves. The `setup cx7` command automates IP assignment and MTU settings.

```bash
# Step 1: Register cluster with management IPs
sparkrun cluster create mylab \
  --hosts 10.24.11.13,10.24.11.14 \
  --user dgxuser \
  -d "2-node DGX Spark cluster"
sparkrun cluster set-default mylab

# Step 2: SSH setup (prompts for passwords, uses default cluster)
sparkrun setup ssh

# Step 3: Configure CX-7 interfaces (uses default cluster)
sparkrun setup cx7
```

--------------------------------

### Sparkrun Command-Line Examples

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/format.mdx

Demonstrates basic sparkrun commands for launching recipes with default or overridden configurations.

```bash
sparkrun run my-recipe --solo          # use defaults
sparkrun run my-recipe -H host1,host2  # override hosts
sparkrun run my-recipe -o port=9000    # override any default
```

--------------------------------

### Run and Inspect Spark Arena Recipes with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Execute inference jobs using recipes from Spark Arena via their short links. You can also inspect recipes for VRAM estimation or save them locally for customization.

```bash
# Run a recipe from Spark Arena using its short linksparkrun run @spark-arena/<recipe-id>

# Inspect it first with VRAM estimationsparkrun show @spark-arena/<recipe-id>

# Save a copy locally for customizationsparkrun show @spark-arena/<recipe-id> --save my-recipe.yaml
```

--------------------------------

### Benchmark Command Usage and Examples

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/benchmark.md

Demonstrates the basic usage and various examples of the /sparkrun:benchmark command. It shows how to specify a recipe and common options like --solo, --tp, --profile, --skip-run, and --no-stop.

```bash
/sparkrun:benchmark <recipe> [options]

/sparkrun:benchmark qwen3-1.7b-sglang --solo
/sparkrun:benchmark qwen3-1.7b-sglang --tp 2 --profile spark-arena-v1
/sparkrun:benchmark qwen3-1.7b-sglang --skip-run --solo
/sparkrun:benchmark qwen3-1.7b-sglang --no-stop --cluster mylab
```

--------------------------------

### Set up sparkrun tab completion

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/installation.mdx

Sets up tab completion for the sparkrun command after a manual pip installation. This command assumes 'sparkrun' is in your system's PATH.

```bash
# NOTE: relies on the 'sparkrun' command being in your PATH
sparkrun setup completion
```

--------------------------------

### Running a Sparkrun Recipe (Bash)

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/registries.mdx

Example command to run a registered Sparkrun recipe. It uses the `@registry/recipe-name` syntax to specify the recipe and allows for specifying host information.

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

--------------------------------

### Python Client Example

Source: https://context7.com/scitrera/sparkrun/llms.txt

Example of using the OpenAI Python SDK to interact with the Sparkrun OpenAI-compatible API.

```APIDOC
## Python Client Example

### Description
This example demonstrates how to use the `openai` Python SDK to communicate with the Sparkrun OpenAI-compatible API endpoint.

### Method
Python Script

### Endpoint
N/A (Code Example)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (handled by the SDK)

### Request Example
```python
from openai import OpenAI

client = OpenAI(
    base_url="http://192.168.11.13:8000/v1",
    api_key="not-needed"  # No auth required by default
)

response = client.chat.completions.create(
    model="Qwen/Qwen3-1.7B",
    messages=[{"role": "user", "content": "Hello, how are you?"}],
    max_tokens=100
)
print(response.choices[0].message.content)
```

### Response
#### Success Response
Output from the LLM based on the prompt.

#### Response Example
```
I am doing well, thank you for asking!
```
```

--------------------------------

### Install Sparkrun using uv

Source: https://context7.com/scitrera/sparkrun/llms.txt

Installs Sparkrun using uv, a fast Python package installer and resolver. It first installs uv itself, then uses uvx to install sparkrun with virtual environment and shell completion.

```bash
# Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Automatic installation with virtual environment and shell completion
uvx sparkrun setup install
```

--------------------------------

### Configure CX-7 Networking with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Automate the configuration of high-speed ConnectX-7 interfaces on Spark nodes, including static IPs, jumbo frames, and netplan. Use `--dry-run` to preview changes.

```bash
sparkrun setup cx7
```

--------------------------------

### Sparkrun Recipe File Format Example

Source: https://context7.com/scitrera/sparkrun/llms.txt

An example of the YAML format for creating custom Sparkrun recipes. This defines the model, container, runtime, and default parameters for an inference workload.

```yaml
model:
  source: "huggingface"
  id: "mistralai/Mistral-7B-Instruct-v0.2"
  dtype: "fp16"
  quantization: "awq"
  # Use `load_format: "gguf"` for llama.cpp runtime

container:
  # Use a pre-built image or provide a Dockerfile path
  image: "ghcr.io/huggingface/text-generation-inference:2.3.0"
  # Or build from Dockerfile:
  # dockerfile: "./Dockerfile"

runtimes:
  # Specify the inference runtime and its configuration
  vllm:
    # Tensor parallelism (number of GPUs to use for a single model replica)
    tp: 1
    # Max batch size
    max_batch_size: 1024
    # Max sequence length
    max_model_len: 4096
    # GPU memory utilization percentage
    gpu_memory_utilization: 0.9

# You can also specify defaults for other runtimes like:
# llama.cpp:
#   n_gpu_layers: -1 # -1 means all layers to GPU
#   n_ctx: 4096
#   n_batch: 512
#   use_mlock: true

# Default parameters for the run command
defaults:
  port: 80
  # You can override any parameter on the fly using `-o` flag
  # e.g., sparkrun run <recipe> -o max_batch_size=512
```

--------------------------------

### Install sparkrun with uvx

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/installation.mdx

Installs sparkrun using uvx, which manages virtual environments, shell aliases, and tab completion. This is the recommended installation method for ease of use.

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install sparkrun (manages venv + shell alias + tab completion)
uvx sparkrun setup install
```

--------------------------------

### Manage Custom Recipe Registries with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Configure and manage custom recipe registries to access community or private recipe sources. This includes listing, adding, updating, and searching across registries.

```bash
# See configured registriessparkrun registry list

# Add a community or private registrysparkrun registry add https://github.com/myorg/spark-recipes.git

# Update all registriessparkrun registry update

# Search across all registriessparkrun search qwen3
```

--------------------------------

### Container Field Examples YAML

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/format.mdx

Provides examples of specifying different Docker/OCI container images for various runtimes.

```yaml
container: scitrera/dgx-spark-vllm:0.16.0-t5
container: scitrera/dgx-spark-sglang:0.5.8-t5
container: scitrera/dgx-spark-llama-cpp:b8076-cu131
```

--------------------------------

### Check Required Packages

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/networking.mdx

This command verifies the presence of essential packages like `rsync`, `git`, and `docker` on DGX OS. If any are missing, the subsequent command installs them using `apt-get`.

```bash
# Confirm these are available
which rsync git docker

# If anything is missing:
sudo apt-get update && sudo apt-get install -y rsync git
```

--------------------------------

### vLLM Triton Kernel Autotuning Examples

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/cli/tune.mdx

These examples illustrate how to use `sparkrun tune` for vLLM recipes. They show tuning for default TP sizes, specific TP sizes, multiple TP sizes, parallel tuning jobs, and dry runs. The generated configurations are stored in `~/.cache/sparkrun/tuning/vllm/` and automatically integrated via the `VLLM_TUNED_CONFIG_FOLDER` environment variable.

```bash
# Tune for all default TP sizes (1, 2, 4, 8) sparkrun tune vllm qwen3-moe-vllm -H 127.0.0.1

# Tune for a specific TP size sparkrun tune vllm qwen3-moe-vllm -H 127.0.0.1 --tp 4

# Tune for multiple specific TP sizes sparkrun tune vllm qwen3-moe-vllm -H 127.0.0.1 --tp 1 --tp 2 --tp 4

# Tune with 4 parallel jobs sparkrun tune vllm qwen3-moe-vllm -H 127.0.0.1 -j4

# Preview without running sparkrun tune vllm qwen3-moe-vllm -H 127.0.0.1 --dry-run
```

--------------------------------

### Install sparkrun CLI

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/README.md

Instructions for installing the sparkrun command-line interface (CLI). It recommends using uvx for installation but also provides an alternative using uv.

```bash
# Install via uvx (recommended)
uvx sparkrun setup install

# Or via uv
uv tool install sparkrun
```

--------------------------------

### SGLang Triton Kernel Autotuning Examples

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/cli/tune.mdx

These examples demonstrate how to use `sparkrun tune` for SGLang recipes. They cover tuning for all default tensor parallel (TP) sizes, specific TP sizes, multiple TP sizes, parallel tuning jobs, and dry runs to preview the process. The tuning results are saved to `~/.cache/sparkrun/tuning/sglang/` and automatically mounted via `SGLANG_MOE_CONFIG_DIR`.

```bash
# Tune for all default TP sizes (1, 2, 4, 8) sparkrun tune sglang qwen3.5-35b-bf16-sglang -H 127.0.0.1

# Tune for a specific TP size sparkrun tune sglang qwen3.5-35b-bf16-sglang -H 127.0.0.1 --tp 2

# Tune for multiple specific TP sizes sparkrun tune sglang qwen3.5-35b-bf16-sglang -H 127.0.0.1 --tp 1 --tp 2 --tp 4

# Tune with 4 parallel jobs sparkrun tune sglang qwen3.5-35b-bf16-sglang -H 127.0.0.1 -j4

# Preview without running sparkrun tune sglang qwen3.5-35b-bf16-sglang -H 127.0.0.1 --dry-run
```

--------------------------------

### Verify sparkrun installation

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/installation.mdx

Checks if sparkrun has been installed correctly by displaying its version number. This is a simple verification step.

```bash
sparkrun --version
```

--------------------------------

### sparkrun Slash Commands Usage Examples

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/README.md

Examples demonstrating how to use the sparkrun slash commands for managing LLM inference workloads. These commands cover running, checking status, listing, and benchmarking recipes.

```bash
/sparkrun:run qwen3-1.7b-vllm --tp 2
/sparkrun:status
/sparkrun:list qwen3
/sparkrun:benchmark qwen3-1.7b-sglang --solo --profile spark-arena-v1
```

--------------------------------

### Command Field Example YAML

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/format.mdx

Demonstrates the use of placeholder substitution within the command field for dynamic parameter injection.

```yaml
command: |
  vllm serve \
      {model} \
      --served-model-name {served_model_name} \
      --host {host} \
      --port {port}
```

--------------------------------

### Install sparkrun using uvx

Source: https://github.com/scitrera/sparkrun/blob/main/README.md

Installs sparkrun using the uvx tool, which manages virtual environments, creates shell aliases, and sets up autocomplete. uvx is the preferred method for managing Python environments.

```bash
# uv is preferred mechanism for managing python environments
# To install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

# automatic installation via uvx (manages virtual environment and
# creates alias in your shell, sets up autocomplete too!)
uvx sparkrun setup install
```

--------------------------------

### Full Sparkrun Recipe Example YAML

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/format.mdx

An extensive sparkrun recipe including metadata, advanced defaults, environment variables, and a detailed command.

```yaml
model: nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-NVFP4
model_revision: abc123def
runtime: vllm
min_nodes: 1
container: scitrera/dgx-spark-vllm:0.16.0-t5

metadata:
  description: NVIDIA Nemotron 3 Nano 30B (upstream NVFP4) -- cluster or solo
  maintainer: scitrera.ai <open-source-team@scitrera.com>
  model_params: 30B
  model_dtype: nvfp4

defaults:
  port: 8000
  host: 0.0.0.0
  tensor_parallel: 1
  gpu_memory_utilization: 0.8
  max_model_len: 200000
  served_model_name: nemotron3-30b-a3b
  tool_call_parser: qwen3_coder

env:
  VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"

command: |
  vllm serve \
      {model} \
      --served-model-name {served_model_name} \
      --max-model-len {max_model_len} \
      --gpu-memory-utilization {gpu_memory_utilization} \
      -tp {tensor_parallel} \
      --host {host} \
      --port {port} \
      --enable-auto-tool-choice \
      --tool-call-parser {tool_call_parser} \
      --trust-remote-code
```

--------------------------------

### Set Up SSH Mesh with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Automate the setup of passwordless SSH access from the control machine to each Spark node, which is required for sparkrun orchestration.

```bash
sparkrun setup ssh
```

--------------------------------

### Run Multi-Node Tensor Parallel Inference with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Launch inference jobs across multiple nodes using tensor parallelism. This example uses a default cluster and specifies a tensor parallel degree of 2.

```bash
# Multi-node tensor parallel using your default clustersparkrun run qwen3-1.7b-vllm --tp 2

# Override settings on the flysparkrun run qwen3-1.7b-vllm --hosts 192.168.11.14 --port 9000 --gpu-mem 0.8sparkrun run qwen3-1.7b-vllm --tp 2 -H 192.168.11.13,192.168.11.14 -o max_model_len=8192
```

--------------------------------

### Clear Page Cache (Optional)

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Frees cached file data to maximize available memory for inference on a specified cluster.

```bash
sparkrun setup clear-cache --cluster <name>
```

--------------------------------

### Comprehensive Benchmark Command Example (Bash)

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/cli/benchmark.mdx

This bash command demonstrates how to run a comprehensive benchmark using Sparkrun with the llama-benchy framework. It specifies various parameters like prompt processing tokens, token generation counts, context depths, concurrency levels, and enables prefix caching measurement.

```bash
# Example: comprehensive benchmarksparkrun benchmark my-recipe --solo \
  -o pp=2048 \
  -o tg=32,128 \
  -o depth=0,4096,16384,65536 \
  -o concurrency=1,2,5,10 \
  -o prefix_caching=true
```

--------------------------------

### Apply Manual Netplan Configuration

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/networking.mdx

These bash commands apply the manually created netplan configuration file. First, the file permissions are set to be secure, and then `netplan apply` is executed to activate the new network settings.

```bash
sudo chmod 600 /etc/netplan/40-cx7.yaml
sudo netplan apply
```

--------------------------------

### Set Up SSH Mesh for Multi-Node Inference

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Configures passwordless SSH for multi-node inference within a specified cluster. This command is interactive and requires password input.

```bash
sparkrun setup ssh --cluster <name>
```

--------------------------------

### Launch and Query OpenAI-Compatible API

Source: https://context7.com/scitrera/sparkrun/llms.txt

Shows how to launch an inference workload with Sparkrun and then query the exposed OpenAI-compatible API endpoint using curl.

```bash
# Launch inferencesparkrun run qwen3-1.7b-vllm --solo --port 8000

# Query the API (from the host or network)
curl http://192.168.11.13:8000/v1/models

curl http://192.168.11.13:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-1.7B",
    "messages": [{"role": "user", "content": "Hello, how are you?"}],
    "max_tokens": 100
  }'
```

--------------------------------

### Manage Sparkrun Clusters

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/skills/setup/SKILL.md

Commands for creating, viewing, setting default, updating, and deleting cluster configurations. Clusters are defined by named host groups stored in `~/.config/sparkrun/clusters/`.

```bash
# Create a cluster (first host = head node)
sparkrun cluster create <name> --hosts <ip1>,<ip2>,... [-d "description"] [--user <ssh_user>]

# Set as default (used when --hosts/--cluster not specified)
sparkrun cluster set-default <name>

# View clusters
sparkrun cluster list
sparkrun cluster show <name>
sparkrun cluster default

# Modify
sparkrun cluster update <name> --hosts <new_hosts> [--user <user>] [-d "desc"]
sparkrun cluster delete <name>
sparkrun cluster unset-default
```

--------------------------------

### Browse and Inspect sparkrun Recipes

Source: https://github.com/scitrera/sparkrun/blob/main/README.md

Explains how to discover and examine available inference recipes. The `show` command includes a VRAM estimator to check model compatibility with DGX Spark's memory.

```bash
# List all available recipes
sparkrun list

# Search by name or model
sparkrun search qwen3

# Inspect a recipe with VRAM estimation
sparkrun show nemotron3-nano-30b-nvfp4-vllm
```

--------------------------------

### Configure DGX Spark Cluster

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Creates a new DGX Spark cluster with specified hosts and description, then sets it as the default. Requires DGX Spark host IPs and an SSH user.

```bash
sparkrun cluster create <name> --hosts <ip1>,<ip2>,... -d "<description>" --user <ssh_user>
sparkrun cluster set-default <name>
```

--------------------------------

### Full Benchmark Flow Example

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/benchmark.md

Illustrates the underlying bash command executed by the /sparkrun:benchmark command for the full benchmark flow, including launching inference, benchmarking, and stopping the server.

```bash
# Full flow: launch inference -> benchmark -> stop
sparkrun benchmark <recipe> [options]
```

--------------------------------

### Fix File Permissions in HuggingFace Cache (Optional)

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/commands/setup.md

Corrects file ownership issues in the HuggingFace cache caused by Docker containers. Optionally saves a sudoers entry for passwordless future runs.

```bash
sparkrun setup fix-permissions --cluster <name>
sparkrun setup fix-permissions --cluster <name> --save-sudo
```

--------------------------------

### Set Up SSH Mesh for Multi-Node Inference

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/skills/setup/SKILL.md

Configures passwordless SSH access between hosts in a cluster, essential for multi-node inference. This script can be run interactively and supports including or excluding specific hosts.

```bash
# Set up SSH mesh across cluster hosts (interactive -- prompts for passwords)
sparkrun setup ssh --cluster <name>
sparkrun setup ssh --hosts <ip1>,<ip2> [--user <username>]

# Include extra hosts (e.g. control machine) in the mesh
sparkrun setup ssh --cluster <name> --extra-hosts <control_ip>

# Exclude the local machine from the mesh
sparkrun setup ssh --cluster <name> --no-include-self

# Dry-run to see what would happen
sparkrun setup ssh --cluster <name> --dry-run
```

--------------------------------

### Manage Sparkrun Workloads (Logs and Stop)

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Re-attach to the logs of a running inference job or stop a workload. Ensure to use matching flags like `--tp` if they were used during job launch.

```bash
# Re-attach to logs (Ctrl+C is always safe)sparkrun logs nemotron3-nano-30b-nvfp4-vllm --cluster mylab

# Stop a workloadsparkrun stop nemotron3-nano-30b-nvfp4-vllm --cluster mylab

# Example with --tp flagsparkrun run nemotron3-nano-30b-nvfp4-vllm --tp 2sparkrun stop nemotron3-nano-30b-nvfp4-vllm --tp 2sparkrun logs nemotron3-nano-30b-nvfp4-vllm --tp 2
```

--------------------------------

### Create and Set Default Sparkrun Cluster

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Register DGX Spark hosts to create a named cluster for easier multi-node job management. The first host listed becomes the head node.

```bash
sparkrun cluster create mylab \
  --hosts 10.24.11.13,10.24.11.14 \
  --user dgxuser \
  -d "My DGX Spark lab"
sparkrun cluster set-default mylab
```

--------------------------------

### Browse and Search Sparkrun Recipes

Source: https://context7.com/scitrera/sparkrun/llms.txt

Commands for listing, searching, and inspecting available inference recipes. Includes filtering by runtime, searching by keywords, showing detailed recipe information with VRAM estimation, saving recipes locally, validating, and estimating VRAM.

```bash
# List all available recipes
sparkrun list

# List recipes filtered by runtime
sparkrun list --runtime vllm
sparkrun list --runtime sglang

# Search recipes by name, model, or description
sparkrun search qwen3
sparkrun search llama --runtime llama-cpp

# Show detailed recipe information with VRAM estimation
sparkrun show nemotron3-nano-30b-nvfp4-vllm

# Show recipe with custom tensor parallelism for VRAM estimate
sparkrun show nemotron3-nano-30b-nvfp4-vllm --tp 2

# Save a recipe locally for customization
sparkrun show nemotron3-nano-30b-nvfp4-vllm --save my-recipe.yaml

# Validate a recipe file
sparkrun recipe validate my-recipe.yaml

# Estimate VRAM usage for a recipe
sparkrun recipe vram glm-4.7-flash-awq --tp 2 --max-model-len 8192
```

--------------------------------

### List and Show Sparkrun Recipes

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/recipes/writing-recipes.mdx

These bash commands are used to list available sparkrun recipes and display the full configuration of a specific recipe. They are useful for understanding the existing recipe ecosystem and inspecting recipe details.

```bash
# See what's available
sparkrun list

# Show a recipe's full configurationsparkrun show qwen3-1.7b-vllm
```

--------------------------------

### Run Inference on Single Node with Sparkrun

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/getting-started/quick-start.mdx

Execute inference jobs on a single DGX Spark node. Defaults to localhost if no host is specified. Supports GGUF quantized models via llama.cpp.

```bash
# Run on a single DGX Spark (defaults to localhost if no host specified)
sparkrun run qwen3-1.7b-vllm

# Run on a specific remote hostsparkrun run qwen3-1.7b-vllm --hosts 10.24.11.13

# GGUF quantized models via llama.cppsparkrun run qwen3-1.7b-llama-cpp
```

--------------------------------

### Clear Linux Page Cache

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/skills/setup/SKILL.md

Frees up system memory on cluster hosts by dropping the Linux page cache. This command can be applied to specified clusters or hosts and supports saving sudoers entries for passwordless execution.

```bash
# Clear cache on cluster hosts
sparkrun setup clear-cache --cluster <name>
sparkrun setup clear-cache --hosts <ip1>,<ip2>

# Install sudoers entry for passwordless future runs
sparkrun setup clear-cache --cluster <name> --save-sudo

# Dry-run
sparkrun setup clear-cache --cluster <name> --dry-run
```

--------------------------------

### Configure CX7 Networking

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/skills/setup/SKILL.md

Automates the configuration of ConnectX-7 network interfaces on cluster hosts for high-speed data transfers. It supports auto-detection, custom subnet overrides, forcing reconfiguration, and setting MTU. Requires passwordless sudo.

```bash
# Auto-detect CX7 interfaces and configure with defaults
sparkrun setup cx7 --cluster <name>
sparkrun setup cx7 --hosts <ip1>,<ip2>

# Override subnets
sparkrun setup cx7 --cluster <name> --subnet1 192.168.11.0/24 --subnet2 192.168.12.0/24

# Force reconfiguration and set MTU
sparkrun setup cx7 --cluster <name> --force --mtu 9000

# Dry-run
sparkrun setup cx7 --cluster <name> --dry-run
```

--------------------------------

### Install sparkrun Plugin

Source: https://github.com/scitrera/sparkrun/blob/main/sparkrun-cc-plugin/README.md

Commands to install the sparkrun plugin for Claude Code, either from the marketplace or manually. The marketplace installation involves adding the marketplace and then installing the plugin. Manual installation requires copying the plugin directory.

```bash
# Add the marketplace (one-time setup)
claude plugin marketplace add scitrera/sparkrun

# Install the plugin
claude plugin install sparkrun@sparkrun
```

```bash
# Global (available in all projects)
cp -r sparkrun-cc-plugin ~/.claude/plugins/sparkrun

# Or project-local
cp -r sparkrun-cc-plugin .claude/plugins/sparkrun
```

--------------------------------

### Configure CX-7 Network Interfaces

Source: https://github.com/scitrera/sparkrun/blob/main/website/src/content/docs/cli/setup-commands.mdx

Configures ConnectX-7 network interfaces for high-speed communication. It detects interfaces, assigns IPs from conflict-free subnets, sets jumbo frames (MTU 9000), and applies netplan configuration. Existing configurations are preserved unless `--force` is used.

```bash
sparkrun setup cx7 --hosts 10.24.11.13,10.24.11.14sparkrun setup cx7 --cluster mylab --dry-runsparkrun setup cx7 --cluster mylab --subnet1 192.168.11.0/24 --subnet2 192.168.12.0/24sparkrun setup cx7 --cluster mylab --force
```