Skip to content

Updates & Telemetry

Terminal window
sparkrun update

This 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.

Terminal window
sparkrun update --no-update-plugins
sparkrun setup update --no-update-plugins --no-update-registries

The 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.

sparkrun tracks three channels. With no flag, sparkrun update stays on your current channel; passing a flag switches to that channel and updates.

ChannelFlagSource
Stable--stablePyPI releases
Beta--betathe develop branch
Alpha--alpha (or --yolo)the develop-next branch
Terminal window
sparkrun update --beta # switch to beta and update
sparkrun update # stay on beta from now on
sparkrun update --stable # switch back

The 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.

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.

For a single command, without touching config:

Terminal window
SPARKRUN_NO_TELEMETRY=1 sparkrun run my-recipe

Prefer this when only some of your runs are sensitive — the rest still contribute the signal the project relies on.

To opt out persistently:

Terminal window
sparkrun setup telemetry --disable # persist the opt-out
sparkrun setup telemetry # show the current setting
sparkrun setup telemetry --enable # turn it back on

The 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.

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.

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:

SentWhen
Qwen/Qwen3-1.7BThe 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.