Updates & Telemetry
Updating
Section titled “Updating”sparkrun updateThis upgrades core when installed as a uv tool, reconciles compatible trusted managed plugins, and refreshes recipe registries. sparkrun setup update is the same command. Both accept --no-update-registries and --no-update-plugins, and both exit nonzero when the core upgrade fails.
If sparkrun was installed some other way — pip, pipx, or an editable
checkout — the core self-upgrade step is skipped; plugin reconciliation and registry refresh still apply.
Plugin reconciliation and state
Section titled “Plugin reconciliation and state”sparkrun update --no-update-pluginssparkrun setup update --no-update-plugins --no-update-registriesThe opt-out still audits local compatibility, including disabled/unmanaged plugins,
but fetches no plugin revisions and does not report remote update availability.
Unmanaged sources are never rewritten. Incompatible/unknown candidates and failed
load checks leave active generations intact. Other updates continue after a
failure: explicit plugins update reports partial failure with a nonzero status.
Failed/unverifiable core upgrades
permit an audit only. See Managed Plugins for pins and rollback.
Stop/drain daemon and worker leases before replacing their interpreter environment; restart long-lived plugin consumers after updates. The managed store is config- adjacent and independent of the core environment. See What’s New in 0.4.0 for the changes in this release.
Release channels
Section titled “Release channels”sparkrun tracks three channels. With no flag, sparkrun update stays on your
current channel; passing a flag switches to that channel and updates.
| Channel | Flag | Source |
|---|---|---|
| Stable | --stable | PyPI releases |
| Beta | --beta | the develop branch |
| Alpha | --alpha (or --yolo) | the develop-next branch |
sparkrun update --beta # switch to beta and updatesparkrun update # stay on beta from now onsparkrun update --stable # switch backThe channel also drives feature-flag defaults — a
capability can be on by default for alpha while staying off for stable. You
can preview another channel’s feature set without changing which code you run
by setting features.channel in config.yaml.
Anonymous telemetry
Section titled “Anonymous telemetry”sparkrun collects anonymous usage telemetry, and it is enabled by default. It carries no hostnames, addresses, credentials, or recipe names — see what is collected for the full list, including the one field that can identify your work.
Turning it off
Section titled “Turning it off”For a single command, without touching config:
SPARKRUN_NO_TELEMETRY=1 sparkrun run my-recipePrefer this when only some of your runs are sensitive — the rest still contribute the signal the project relies on.
To opt out persistently:
sparkrun setup telemetry --disable # persist the opt-outsparkrun setup telemetry # show the current settingsparkrun setup telemetry --enable # turn it back onThe environment variable is the single per-process override and beats the
persisted setting either way — a truthy value opts out, a falsy value forces it
on. So SPARKRUN_NO_TELEMETRY=0 re-enables telemetry for one command even when
it is disabled in config. The persisted setting lives at telemetry.enabled in
~/.config/sparkrun/config.yaml.
What is collected
Section titled “What is collected”Events include run, benchmark, update, setup_wizard, and optional daemon_serve. Fields depend on the event; the common envelope includes installation/system/version data and via_daemon attribution. Operation events can include:
- OS name, OS release, and CPU architecture.
- The model identifier from the recipe — but only when it is a repo confirmed publicly readable on HuggingFace (see below) — plus a quantization/dtype summary.
- Runtime, executor, and scheduler names; success/return code; duration; whether the run was solo or a dry run.
- Cluster shape — node count, total GPU count, and accelerator vendor/model counts. Not hostnames or addresses.
- How the recipe was referenced, classified into
spark_arena/url/file/reference— not the recipe name, path, or URL. - Registry counts (total, enabled, non-default) — not registry names or URLs.
- For updates: old/new version, channel, and whether the self-upgrade succeeded. For the wizard: which steps were opted into, skipped, or failed.
Hostnames, IP addresses, SSH usernames, recipe names and paths, registry names, and registry URLs are not sent. Emission is best-effort with a sub-second timeout; reporting failures do not fail the operation.
Model identifiers
Section titled “Model identifiers”The model name is the one field that could describe your work, so it is filtered rather than sent as written. The raw value leaves your machine only when the repo is confirmed publicly readable on HuggingFace. Otherwise it is replaced with a coarse placeholder that records why it was withheld, without naming anything:
| Sent | When |
|---|---|
Qwen/Qwen3-1.7B | The repo is public — the signal the project actually wants |
<hf-private> | The repo is private or gated |
<local-path> | The model is a path to weights on local disk |
<unknown-visibility> | Visibility could not be established |
Visibility comes from the Hub’s own private / gated flags, not from whether
a lookup succeeded. That distinction matters: if you have an HF_TOKEN
configured, your private repos resolve perfectly well, so “it fetched” would
have been the wrong test.
The check fails closed. Offline, rate-limited, a typo’d repo id, or a run
where model detection was skipped all yield <unknown-visibility> rather than
the name — being unable to check is never treated as permission to send.
Local paths are classified without contacting the Hub at all.
Daemon serving lifecycle, via_daemon, and host-side opt-out behavior are detailed
in the daemon reference. The durable
job journal is not uploaded as usage telemetry; monitoring streams are separate.