Skip to content

sparkrun export

The export command group provides tools for exporting recipes in various formats and generating systemd services for persistent inference workloads.

Terminal window
sparkrun export recipe <recipe> [options]

Export a normalized recipe to stdout or a file. Includes are flattened by default, while conditional overrides remain available for future launches. Use --keep-include to retain the original base reference and child settings, or --realize to resolve the recipe for selected hardware.

OptionDescription
--jsonOutput as JSON instead of YAML
--save <path>Save to a file instead of printing to stdout
--keep-includePreserve the original include: reference and child settings
--realizePlan for selected hardware and bake in matching conditional and CLI overrides
--hosts / -H, --hosts-file, --clusterTarget selection for --realize; otherwise use the default cluster
--tp, --pp, --dp, --gpu-mem, --max-model-len, --image, -oRecipe overrides for --realize
--no-pinWith --realize, retain image/model references as written
--offline / --onlineWith --realize, select resident/cached or online pin sources; defaults to the cluster policy
Terminal window
# Print normalized YAML to stdout
sparkrun export recipe qwen3-1.7b-vllm
# Save to a file
sparkrun export recipe qwen3-1.7b-vllm --save my-recipe.yaml
# Export as JSON
sparkrun export recipe qwen3-1.7b-vllm --json

Realization probes the hosts and plans placement as run would, then exports a plain recipe with matching overrides: and CLI settings baked into it. It starts no inference workload. Platform defaults remain platform defaults and are applied again at launch. metadata.realized_for records the selected hardware and node count without host names.

Terminal window
# Resolve conditional settings and pin artifacts for this cluster.
sparkrun export recipe my-recipe --realize --cluster mylab --tp 2 --save realized.yaml
# Capture the versions already available on the selected hosts.
sparkrun export recipe my-recipe --realize --cluster mylab --offline --save resident.yaml
# Bake in settings while retaining the original image/model references.
sparkrun export recipe my-recipe --realize --cluster mylab --no-pin
# Keep a child recipe's include instead of flattening it.
sparkrun export recipe child.yaml --keep-include --save child-copy.yaml

By default, container references are pinned to registry digests and the primary model to a Hugging Face commit. metadata.pinned records the references replaced and their provenance. Offline pinning uses resident images and cached models; selected hosts must agree on image content. A matching controller image can supply a missing registry digest, and the controller cache can supply model metadata when absent on a target.

Pinning has limits: locally built images can require --no-pin, and a separate draft model in speculative_config.model is not automatically pinned. It is reported as unpinned unless speculative_config.revision is already supplied. Inspect the export diagnostics for unresolved or unpinned assets. Online image lookup uses anonymous access or inline Docker credentials; it does not invoke Docker credential helpers.

Host selection, recipe overrides, and pinning flags require --realize. --keep-include cannot be combined with --realize, and --offline cannot be combined with --no-pin.

Terminal window
sparkrun export running-recipe <target> [options]

Export the effective recipe from a running workload, including all applied overrides baked into defaults. This is useful for capturing the exact configuration of a running inference workload.

TARGET can be a recipe name or a workload ID (the short hex string from sparkrun status output).

OptionDescription
--hosts / -HComma-separated host list (needed when target is a recipe name)
--hosts-fileFile with hosts
--clusterUse a saved cluster by name
--jsonOutput as JSON instead of YAML
--save <path>Save to a file instead of printing to stdout
Terminal window
# Export by workload ID (from sparkrun status)
sparkrun export running-recipe e5f6a7b8
# Export by recipe name (requires host/cluster info)
sparkrun export running-recipe glm-4.7-flash-awq --cluster mylab
# Save to a file
sparkrun export running-recipe e5f6a7b8 --save effective-recipe.yaml
# Export as JSON
sparkrun export running-recipe e5f6a7b8 --json
Terminal window
sparkrun export systemd <target> --cluster <name> [options]

Generate a systemd service for running a sparkrun inference workload persistently on the head node of a cluster. The service wraps sparkrun run with --foreground, giving you journald log integration, systemctl status monitoring, and automatic restart on failure.

TARGET can be a recipe name (with optional overrides) or a workload ID.

The exported cluster retains the source cluster’s full host list, SSH user, executor, transport, scheduler, and other settings. Placement happens on each service start. Controller-local env_file values are resolved during export and written into the head node’s owner-only cluster file. Service names and SSH users are validated; an omitted SSH user falls back to the local login.

Python frontends can use the experimental api.systemd_export helpers to plan, render, and install these artifacts separately.

OptionDescription
--hosts / -HComma-separated host list
--hosts-fileFile with hosts
--clusterUse a saved cluster by name
--tp / --tensor-parallelOverride tensor parallelism
--pp / --pipeline-parallelOverride pipeline parallelism
--gpu-memOverride GPU memory utilization
--max-model-lenOverride maximum model context length
--option / -oOverride a default (key=value) or mapping field (key.field=value); repeatable
--imageOverride container image
--portOverride service port
--served-model-nameOverride served model name
--installDeploy service to the head node
--uninstallRemove service from the head node
--startStart service after install (implies --install)
--service-nameOverride service name (default: sparkrun-<slug>)
--dry-run / -nShow what would be done

Preview (default) — prints all generated artifacts for review:

Terminal window
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab

This displays the systemd unit file, baked recipe, cluster definition, install script, and uninstall script without making any changes.

Install — deploys the service to the head node:

Terminal window
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --install

This SSHes to the head node and:

  1. Creates the service directory (~/.config/sparkrun/services/<slug>/)
  2. Writes the baked recipe and cluster definition
  3. Installs the systemd unit file (requires sudo)
  4. Enables the service with systemctl enable

Install and start — deploys and immediately starts the service:

Terminal window
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --install --start

Uninstall — removes the service from the head node:

Terminal window
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --uninstall

This stops the service, disables it, removes the unit file, and cleans up service files.

You can generate a systemd service from an already-running workload using its workload ID:

Terminal window
sparkrun export systemd e5f6a7b8 --install --start

After --install, the following files are created:

~/.config/sparkrun/
services/<slug>/
recipe.yaml # Baked recipe with all overrides
cluster.yaml # Cluster definition reference
clusters/
<slug>-systemd.yaml # Cluster definition used by the service
/etc/systemd/system/
sparkrun-<slug>.service # systemd unit file (requires sudo)

Once installed, use standard systemd commands on the head node:

Terminal window
# Check status
systemctl status sparkrun-<slug>
# View logs
journalctl -u sparkrun-<slug> -f
# Start / stop / restart
sudo systemctl start sparkrun-<slug>
sudo systemctl stop sparkrun-<slug>
sudo systemctl restart sparkrun-<slug>

The generated unit uses:

  • Type=simple — sparkrun runs in foreground mode, so systemd tracks the process directly
  • Restart=on-failure with RestartSec=30 — automatic recovery from crashes
  • TimeoutStartSec=600 — allows time for large model loading
  • TimeoutStopSec=120 — allows time for graceful Docker container shutdown
  • StandardOutput=journal / StandardError=journal — all logs go to journald