---
title: Quick Start
description: Get up and running with sparkrun in minutes.
---

## Single-node usage

No cluster setup needed — just point sparkrun at a host and run:

```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 host
sparkrun run qwen3-1.7b-vllm --hosts 10.24.11.13

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

sparkrun launches jobs in the background (detached containers) and follows logs. **Ctrl+C detaches from logs — it never kills your inference job.** Your model keeps serving.

## Multi-node cluster setup

Multi-node inference (tensor parallelism across Sparks) requires three one-time setup steps:

### 1. Register your cluster

Save your DGX Spark hosts using their **management network IPs** (the built-in 10 Gbps Ethernet). This makes subsequent commands shorter — they reference the cluster by name instead of repeating host lists:

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

The first host becomes the **head node** for multi-node jobs. Order remaining hosts however you like — they become workers.

:::tip
If the machine you're running sparkrun from is also a cluster member, use `127.0.0.1` for it in the host list (e.g., `--hosts 127.0.0.1,10.24.11.14`). This avoids SSH-to-self issues and is slightly more efficient for local operations.
:::

### 2. Set up SSH Mesh

sparkrun orchestrates over SSH. Establish passwordless SSH from your control machine to each Spark:

```bash
sparkrun setup ssh
```

This is interactive — you'll be prompted for passwords. See [SSH Setup](/getting-started/ssh-setup/) for details.

### 3. Configure CX-7 networking

Configure the high-speed ConnectX-7 interfaces on each Spark. This assigns static IPs, sets up jumbo frames (MTU 9000), and applies netplan — all automated over SSH:

```bash
sparkrun setup cx7
```

This detects CX-7 interfaces, picks two conflict-free subnets, and configures everything. Use `--dry-run` to preview first. See [Networking Best Practices](/getting-started/networking/) for the full guide.

\(If your CX7 interfaces are already set up, you can skip this step -- but also, if they're already setup, then this will make no changes and just check your setup!)

sparkrun automatically discovers the CX-7 interfaces on each host and uses them for high-bandwidth operations (model sync, container distribution, NCCL).

## Run an inference job

```bash
# Single node — minimum nodes/parallelism is set by the recipe
sparkrun run qwen3-1.7b-vllm

# Multi-node tensor parallel using your default cluster
sparkrun run qwen3-1.7b-vllm --tp 2

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

## Inspect a recipe

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

This displays recipe details including a VRAM estimation that tells you whether the configuration fits DGX Spark's 128 GB unified memory before you launch.

## Manage running workloads

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

# Stop a workload
sparkrun stop nemotron3-nano-30b-nvfp4-vllm --cluster mylab
```

:::note
If you launched with `--tp` (modifying the recipe default), pass the same `--tp` flag to `stop` and `logs` so they resolve the same cluster ID:

```bash
sparkrun run nemotron3-nano-30b-nvfp4-vllm --tp 2
sparkrun stop nemotron3-nano-30b-nvfp4-vllm --tp 2
sparkrun logs nemotron3-nano-30b-nvfp4-vllm --tp 2
```
:::

## Spark Arena recipes

[Spark Arena](https://spark-arena.com) is the community recipe hub for DGX Spark. Browse tested recipes and benchmark results, then run them directly:

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

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

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

Spark Arena recipes are also included in sparkrun's default registries — `sparkrun list` shows them automatically.

## Custom recipe registries

```bash
# See configured registries
sparkrun registry list

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

# Update all registries
sparkrun registry update

# Search across all registries
sparkrun search qwen3
```

See [Registries](/recipes/registries/) for more details.
