---
title: Setup Commands
description: Install sparkrun, configure networking, permissions, and cluster prerequisites.
---

## Install sparkrun

```bash
sparkrun setup install
```

Installs sparkrun on PATH as a managed uv tool with tab completion. This is the recommended installation method.

## Shell tab-completion

```bash
sparkrun setup completion              # auto-detects your shell
sparkrun setup completion --shell zsh  # specify shell explicitly
```

After restarting your shell, recipe names, cluster names, and subcommands all tab-complete.

:::note
If you installed via `sparkrun setup install`, tab completion is already configured.
:::

## Update sparkrun

```bash
sparkrun setup update
```

Updates sparkrun to the latest version in your managed environment and refreshes all recipe registries. Use `--no-update-registries` to skip the registry update.

## SSH mesh setup

```bash
sparkrun setup ssh [options]
```

Set up passwordless SSH across your cluster hosts. See the [SSH Setup](/getting-started/ssh-setup/) guide for full details.

| Option | Description |
|---|---|
| `--hosts` / `-H` | Comma-separated host list |
| `--hosts-file` | File with hosts (one per line, `#` comments) |
| `--cluster` | Use a saved cluster |
| `--user` | SSH user (default: current OS user) |
| `--extra-hosts` | Additional hosts beyond the cluster |
| `--no-include-self` | Exclude the control machine from the mesh |

## CX-7 network configuration

```bash
sparkrun setup cx7 [options]
```

Configure ConnectX-7 network interfaces on cluster hosts for high-speed NCCL/RDMA communication. Detects CX-7 interfaces via SSH, selects two conflict-free `/24` subnets, assigns static IPs with jumbo frames (MTU 9000), and applies netplan configuration.

Existing valid configurations are preserved unless `--force` is used. IP addresses are derived from each host's management IP last octet (e.g., management `10.24.11.13` → CX-7 `192.168.11.13` and `192.168.12.13`).

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

| Option | Description |
|---|---|
| `--hosts` / `-H` | Comma-separated host list (management IPs or hostnames) |
| `--hosts-file` | File with hosts (one per line, `#` comments) |
| `--cluster` | Use a saved cluster definition |
| `--user` / `-u` | SSH username (default: from cluster config or current user) |
| `--subnet1` | Override subnet for CX-7 partition 1 (e.g., `192.168.11.0/24`) |
| `--subnet2` | Override subnet for CX-7 partition 2 (e.g., `192.168.12.0/24`) |
| `--mtu` | MTU for CX-7 interfaces (default: `9000`) |
| `--force` | Reconfigure even if existing config is valid |
| `--dry-run` / `-n` | Show the plan without making changes |

:::note
`--subnet1` and `--subnet2` must be specified together. See the [Networking Best Practices](/getting-started/networking/) guide for subnet selection guidance, verification steps, and manual configuration instructions.
:::

## Fix cache permissions

```bash
sparkrun setup fix-permissions [options]
```

Fix file ownership in the HuggingFace cache on cluster hosts. Docker containers create cache files as root, leaving the normal user unable to manage them. This command runs `chown` across all target hosts to restore ownership.

Tries non-interactive sudo first on all hosts in parallel, then falls back to password-based sudo for any that fail. Use `--save-sudo` to avoid password prompts on subsequent runs.

```bash
sparkrun setup fix-permissions --cluster mylab
sparkrun setup fix-permissions --cluster mylab --cache-dir /data/hf-cache
sparkrun setup fix-permissions --cluster mylab --save-sudo
sparkrun setup fix-permissions --cluster mylab --dry-run
```

| Option | Description |
|---|---|
| `--hosts` / `-H` | Comma-separated host list |
| `--hosts-file` | File with hosts (one per line, `#` comments) |
| `--cluster` | Use a saved cluster definition |
| `--user` / `-u` | Target owner for chown (default: SSH user) |
| `--cache-dir` | Cache directory path (default: `HF_HOME`, typically `~/.cache/huggingface`) |
| `--save-sudo` | Install a scoped sudoers entry for passwordless chown (requires sudo once) |
| `--dry-run` / `-n` | Show what would be done without executing |

Use `--save-sudo` to install a minimal sudoers rule that permits **only** `chown` on the cache directory — no broader privileges are granted. After this, sparkrun automatically fixes cache ownership before every model distribution without prompting for a password.

See [HuggingFace cache owned by root](/getting-started/troubleshooting/#huggingface-cache-owned-by-root) for background and prevention tips.

## Clear page cache

```bash
sparkrun setup clear-cache [options]
```

Drop the Linux page cache on cluster hosts. Runs `sync` followed by writing `3` to `/proc/sys/vm/drop_caches` on each host, freeing cached file data so inference containers have maximum available memory on DGX Spark's unified CPU/GPU memory.

Tries non-interactive sudo first on all hosts in parallel, then falls back to password-based sudo for any that fail. Use `--save-sudo` to avoid password prompts on subsequent runs.

```bash
sparkrun setup clear-cache --cluster mylab
sparkrun setup clear-cache --cluster mylab --save-sudo
sparkrun setup clear-cache --cluster mylab --dry-run
```

| Option | Description |
|---|---|
| `--hosts` / `-H` | Comma-separated host list |
| `--hosts-file` | File with hosts (one per line, `#` comments) |
| `--cluster` | Use a saved cluster definition |
| `--user` / `-u` | Target user for sudoers entry (default: SSH user) |
| `--save-sudo` | Install a scoped sudoers entry for passwordless cache clearing (requires sudo once) |
| `--dry-run` / `-n` | Show what would be done without executing |

Use `--save-sudo` to install a minimal sudoers rule that permits **only** writing to `/proc/sys/vm/drop_caches` — no broader privileges are granted. After this, sparkrun automatically clears the page cache before every container launch without prompting for a password.

See [Linux page cache consuming memory](/getting-started/troubleshooting/#linux-page-cache-consuming-memory) for background on why this matters.
