# Pack

Turns an image, or a machine already provisioned, into a single self-contained artifact...

- Repository: https://github.com/smol-machines/smolvm (6894 stars)
- Category: Media
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add smol-machines/smolvm --skill pack -g -a claude-code -y`
Codex: `npx skills add smol-machines/smolvm --skill pack -g -a codex -y`
Cursor: `npx skills add smol-machines/smolvm --skill pack -g -a cursor -y`
Gemini CLI: `npx skills add smol-machines/smolvm --skill pack -g -a gemini-cli -y`

## Description

Turns an image, or a machine already provisioned, into a single self-contained artifact that runs on another compatible host. Use when shipping a prepared environment as one file, when a packed artifact runs but the state installed into it is missing, when pack create fails because the VM it boots to pull or export could not start, when an older release refuses to export a branched machine, or when deciding whether to pack from an image or from a machine. Do not use it to keep a machine you re-enter, which is the dev-env packet, or to run untrusted code, which is the throwaway-machine packet.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Packing a machine into a portable artifact

For macOS first-import performance, storage seed behavior and a file-heavy
reproduction, see [macOS storage seeds](references/macos-storage-seeds.md).

Verified on **smolvm v1.29.0** on macOS arm64, 2026-10-15, and on **v1.14.6** on Linux aarch64,
2026-09-11; the Linux host could not run the packing steps on v1.18.2 or v1.22.2, for the reason in
"Platform arms". Done means the artifact runs a command in a real VM and, for a machine pack, **the state you installed is still
inside it**.
The Linux runs used the scripts of their date; this version's preflight and cleanup scripts ran
on Linux aarch64 on v1.22.2 on 2026-10-03.

**The assertion that matters is a value, not a boot.** A pack that lost its rootfs still boots,
still prints a guest kernel and still exits zero. The only thing that separates a good artifact
from an empty one is a marker written into the source machine before packing and read back out of
the artifact afterwards, which is what `pack-machine.sh` and `verify-pack.sh` do between them.

## Procedure

**1. Preflight.** Read-only: starts no VM, packs nothing.

```bash
scripts/preflight.sh
```

The rest: https://github.com/smol-machines/smolvm/blob/HEAD/docs/pack/SKILL.md