Capture and share your work

For your own work, the workflow is capture → run and measure → publish when satisfied. Publication is optional; a successful local capture is enough to run on your compatible placement.

1. Prepare your recipe

Complete the ColdSnap plugin preview setup and run these commands in that activated Sparkrun environment. Start from a recipe appropriate for your hardware and engine. Keep the model revision and runtime image pinned, and verify the normal workload before capturing it.

ColdSnap needs capture and restore components inside the serving container. You can prepare that runtime in either of two ways.

Augment a standard vLLM or SGLang container. Set builder: coldsnap in your recipe. Sparkrun uses the digest-pinned image in container: as the base and builds a derived image with ColdSnap’s runtime components and engine integration added. This is the usual path when starting from a compatible vLLM or SGLang recipe:

# Add to a complete, pinned Sparkrun recipe.
builder: coldsnap
coldsnap: {}

The two settings have different jobs: builder: coldsnap prepares the container image, while the top-level coldsnap: block enables the ColdSnap workflow and configures its capture and restore policy.

Use an already-built ColdSnap runtime container. Set container: to the digest-pinned image that already includes ColdSnap support, omit builder: coldsnap, and keep the top-level coldsnap: {} block. The ColdSnap project plans to publish prebuilt runtime containers in the near future.

Weight selection defaults depend on the engine and snapshot driver. See the complete recipe example and recipe policy and weights when configuring your own image or policy.

If you intend to publish, configure the destination capsule repository before capturing and keep it stable through capture, verification, and publication:

coldsnap:
  capsule:
    repository: docker.io/YOUR_NAMESPACE/YOUR_CAPSULE_REPOSITORY

2. Capture locally

Replace recipe.yaml and two-node with your recipe path and saved cluster name:

sparkrun coldsnap capture recipe.yaml --cluster two-node

Capture initializes the real engine, validates it, and builds the local capsule and artifact descriptor for later runs. It can replace an existing deployment of the same recipe and takes time to initialize, package, and verify the workload.

3. Run and measure

sparkrun run recipe.yaml --cluster two-node

Check the inference response as well as startup performance. Compare the same model, runtime, hardware, topology, and cache conditions. The benchmark methodology measures from container start to the first non-empty streamed token; manager preparation is separate. Use the maintained benchmark harnesses for matched measurements.

Repeat and refine your recipe as needed. A correct restore does not by itself mean the result meets your performance target. Keep captures local until you are satisfied.

4. Publish when satisfied

Make registry authentication available to Sparkrun, then publish explicitly:

sparkrun coldsnap publish recipe.yaml --cluster two-node

To share optional native model payloads, configure Hugging Face authentication for the manager and publish those too:

sparkrun coldsnap publish-native recipe.yaml --cluster two-node \
  --hf-repo YOUR_NAMESPACE/YOUR_NATIVE_PAYLOAD_REPOSITORY

Share the pinned recipe and the immutable artifact/provider references produced by publication, together with your qualified hardware, driver, topology, validation, and measurements. Capsule publication and native-payload publication are separate operations; recovery can use the pinned original model without a native payload repository.

Other users follow the published-capsule workflow: materialize locally → run. Publishing artifacts does not automatically add a recipe to the community registry.