/configuration

name: configuration
description: Install/update Sparkrun 0.4.0, configure host clusters and SSH, check setup, manage plugins/features, and inspect or clean model caches.

Installation and host setup

Check `sparkrun --version` and installed `--help` before assuming optional commands are available. These instructions target 0.4.0. Use the workloads skill for execution and registry for recipes. Keep changes within the user's requested hosts and scope.

Install and update

uv --version
uvx sparkrun setup install
sparkrun --version
sparkrun update
sparkrun update --no-update-plugins
sparkrun setup update --no-update-registries --no-update-plugins
sparkrun update --alpha
sparkrun update --stable

`uvx sparkrun setup` is the guided install/setup entrypoint; `setup install` installs the CLI. Python 3.12+ is required. Ordinary `update` upgrades core, updates trusted managed plugins to compatible versions, and refreshes registries. `--no-update-plugins` skips plugin fetch/update but audits compatibility. Skipping registry updates alone does not skip plugin updates.

Stable uses PyPI; beta uses develop; alpha (`--yolo`) uses develop-next. No channel flag keeps the current channel; switching to stable may downgrade. Do not switch channels merely to expose optional commands. macOS/Windows controller support and Linux inference host support are different: Linux setup and systemd steps are not local macOS/Windows services.

Wizard and read-only checks

sparkrun setup wizard
sparkrun setup wizard --hosts <host1>,<host2> --cluster mylab
sparkrun setup wizard --hosts <host1>,<host2> --dry-run
sparkrun setup check --cluster <name>
sparkrun setup check --cluster <name> --json

`setup` opens the wizard when no default cluster is configured and its feature is on. Registered steps/hardware probes cover SSH mesh/identities, Docker, NVIDIA CDI, CX7, sudoers, IPC reaping, and earlyoom where applicable; do not assume a fixed sequence. `--yes` accepts defaults, not SSH/sudo passwords; it does not guarantee an unattended run.

`setup check` is read-only and detects duplicate SSH host keys and machine IDs. The wizard can offer repair. Rotation is a separate confirmed action:

sparkrun setup ssh-rotate-keys --cluster <name> --dry-run
sparkrun setup ssh-rotate-keys --cluster <name>
sparkrun setup ssh-rotate-keys --cluster <name> --machine-id

This rotates **server host keys**, not login private keys, and refreshes trust/SSH mesh for the same hosts. `--machine-id` also changes OS identities; reboot afterward. Other clients must trust new keys. Do not add `--yes` without existing authorization. If incomplete, report the recovery record; do not discard key mismatch warnings.

Clusters and host steps

sparkrun cluster create mylab --hosts <host1>,<host2> --user <user> -d "My lab"
sparkrun cluster set-default mylab
sparkrun cluster list
sparkrun cluster show mylab
sparkrun cluster default
sparkrun cluster update mylab --add-host <host3>
sparkrun cluster update mylab --remove-host <host3>
sparkrun setup ssh --cluster mylab
sparkrun setup ssh --cluster mylab --extra-hosts <controller_ip>
sparkrun setup ssh --cluster mylab --no-include-self --dry-run
sparkrun setup cx7 --cluster mylab --dry-run
sparkrun setup docker-group --cluster mylab
sparkrun setup fix-permissions --cluster mylab --cache-dir /data/huggingface --dry-run
sparkrun setup clear-cache --cluster mylab --dry-run
sparkrun setup earlyoom --cluster mylab
sparkrun setup diagnose --cluster mylab --output diagnostics.ndjson

Clusters hold candidate hosts; actual placement may select a subset/different head. Incremental changes use `--add-host`/`--remove-host` (repeatable, comma lists). SSH and shared sudo fallback can prompt: use a user terminal. `fix-permissions` and `clear-cache` offer `--save-sudo` for scoped sudoers entries. `clear-cache` drops Linux **page cache**, not model files. Diagnostics are NDJSON; `setup diagnose --json` prints a JSON summary as well as writing the bundle.

Plugins and features

sparkrun plugins
sparkrun plugins list --all --json
sparkrun plugins add https://github.com/sparksq/sparkrun-sparkroute-plugin
sparkrun plugins add https://github.com/sparksq/sparkrun-coldsnap-plugin
sparkrun plugins update --all
sparkrun plugins update <plugin_name>
sparkrun plugins rollback <plugin_name>
sparkrun plugins enable <plugin_name>
sparkrun plugins disable <plugin_name>
sparkrun plugins remove <plugin_name>
sparkrun setup features
sparkrun setup features list --all --json
sparkrun setup features enable gateway.sparkroute
sparkrun setup features disable gateway
sparkrun setup features reset gateway

Prefer top-level `plugins`; `setup plugins` is a hidden alias. No subcommand lists plugins/features. Installation asks for trust in remote executable code and may enable external loading; do not silently add `--trust`. Managed generations are independent of core installs, compatibility checked, and retain current + previous by default (configurable).

Plugin enable/disable controls whole-plugin loading. Feature flags control its capabilities; a flag cannot load a disabled plugin. Installation/update is not explicit feature activation. Plugin list shows declared flags, not on/off values; `setup features` shows effective state. Both list only enabled entries by default (text and JSON, with a "N disabled ... hidden" hint); add `--all` to include disabled plugins/flags (and `setup.steps.*` flags). OCI Relay is bundled and enabled on all channels; use `plugins enable/disable oci_relay`, not a legacy integration flag.

Gateway support defaults on; LiteLLM is bundled/default on every channel. After installing/enabling SparkRoute, explicitly enabling `gateway.sparkroute` selects it; enabling `gateway.litellm` selects LiteLLM. Both provider flags may stay on. Disabling shared `gateway` blocks new activity but does not stop a running proxy. Reset removes an override without activation hoo