sparkrun export
The export command group provides tools for exporting recipes in various formats and generating systemd services for persistent inference workloads.
export recipe
Section titled “export recipe”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.
Options
Section titled “Options”| Option | Description |
|---|---|
--json | Output as JSON instead of YAML |
--save <path> | Save to a file instead of printing to stdout |
--keep-include | Preserve the original include: reference and child settings |
--realize | Plan for selected hardware and bake in matching conditional and CLI overrides |
--hosts / -H, --hosts-file, --cluster | Target selection for --realize; otherwise use the default cluster |
--tp, --pp, --dp, --gpu-mem, --max-model-len, --image, -o | Recipe overrides for --realize |
--no-pin | With --realize, retain image/model references as written |
--offline / --online | With --realize, select resident/cached or online pin sources; defaults to the cluster policy |
Examples
Section titled “Examples”# Print normalized YAML to stdoutsparkrun export recipe qwen3-1.7b-vllm
# Save to a filesparkrun export recipe qwen3-1.7b-vllm --save my-recipe.yaml
# Export as JSONsparkrun export recipe qwen3-1.7b-vllm --jsonRealize for selected hardware
Section titled “Realize for selected hardware”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.
# 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.yamlBy 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.
export running-recipe
Section titled “export running-recipe”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).
Options
Section titled “Options”| Option | Description |
|---|---|
--hosts / -H | Comma-separated host list (needed when target is a recipe name) |
--hosts-file | File with hosts |
--cluster | Use a saved cluster by name |
--json | Output as JSON instead of YAML |
--save <path> | Save to a file instead of printing to stdout |
Examples
Section titled “Examples”# 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 filesparkrun export running-recipe e5f6a7b8 --save effective-recipe.yaml
# Export as JSONsparkrun export running-recipe e5f6a7b8 --jsonexport systemd
Section titled “export systemd”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.
Options
Section titled “Options”| Option | Description |
|---|---|
--hosts / -H | Comma-separated host list |
--hosts-file | File with hosts |
--cluster | Use a saved cluster by name |
--tp / --tensor-parallel | Override tensor parallelism |
--pp / --pipeline-parallel | Override pipeline parallelism |
--gpu-mem | Override GPU memory utilization |
--max-model-len | Override maximum model context length |
--option / -o | Override a default (key=value) or mapping field (key.field=value); repeatable |
--image | Override container image |
--port | Override service port |
--served-model-name | Override served model name |
--install | Deploy service to the head node |
--uninstall | Remove service from the head node |
--start | Start service after install (implies --install) |
--service-name | Override service name (default: sparkrun-<slug>) |
--dry-run / -n | Show what would be done |
Preview (default) — prints all generated artifacts for review:
sparkrun export systemd qwen3-1.7b-vllm --cluster mylabThis 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:
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --installThis SSHes to the head node and:
- Creates the service directory (
~/.config/sparkrun/services/<slug>/) - Writes the baked recipe and cluster definition
- Installs the systemd unit file (requires sudo)
- Enables the service with
systemctl enable
Install and start — deploys and immediately starts the service:
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --install --startUninstall — removes the service from the head node:
sparkrun export systemd qwen3-1.7b-vllm --cluster mylab --uninstallThis stops the service, disables it, removes the unit file, and cleans up service files.
From a running workload
Section titled “From a running workload”You can generate a systemd service from an already-running workload using its workload ID:
sparkrun export systemd e5f6a7b8 --install --startFile layout on head node
Section titled “File layout on head node”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)Managing the service
Section titled “Managing the service”Once installed, use standard systemd commands on the head node:
# Check statussystemctl status sparkrun-<slug>
# View logsjournalctl -u sparkrun-<slug> -f
# Start / stop / restartsudo systemctl start sparkrun-<slug>sudo systemctl stop sparkrun-<slug>sudo systemctl restart sparkrun-<slug>systemd unit details
Section titled “systemd unit details”The generated unit uses:
Type=simple— sparkrun runs in foreground mode, so systemd tracks the process directlyRestart=on-failurewithRestartSec=30— automatic recovery from crashesTimeoutStartSec=600— allows time for large model loadingTimeoutStopSec=120— allows time for graceful Docker container shutdownStandardOutput=journal/StandardError=journal— all logs go to journald