forkd pack, push, pull, unpack, and images commands

The Snapshot Hub is forkd’s mechanism for distributing warmed parent snapshots across hosts. Instead of re-baking a snapshot from Docker on every machine (1–3 minutes), you pack a local snapshot into a single .forkd-snapshot.tar.zst archive (~23× compression typical), upload it once, and other hosts pull and unpack it in seconds. The result is immediately forkable — no Docker round-trip required. Pack files include a manifest.toml with per-file SHA-256 checksums. forkd unpack and forkd pull verify every file against the manifest before moving anything into the snapshot directory, so a corrupted download or a tampered pack is caught before it can poison a snapshot. For v0.5 chain packs, the archive bundles every ancestor link under chain[].files; forkd unpack materializes all links into their respective tag directories in root-to-head order.

`forkd pack`

Pack a local snapshot into a portable .forkd-snapshot.tar.zst archive. The archive includes manifest.toml with per-file SHA-256 checksums, the snapshot’s memory.bin, vmstate, snapshot.json, and any chain-link files for v0.5 chained snapshots. After the pack completes, the CLI prints the output file size, uncompressed size, compression ratio, and a suggested next step.

--tag

string

required

Tag of the local snapshot to pack. Must exist at $XDG_DATA_HOME/forkd/snapshots/<tag>/.

--out

path

Output file path. Default: ./<sanitized-tag>.forkd-snapshot.tar.zst in the current directory. Short form: -o.

--description

string

Human-readable description recorded in the manifest. Optional. Shown by hub registries and forkd images when present.

--base-image

string

Upstream Docker image reference (e.g. python:3.12-slim). Recorded in the manifest as informational metadata. Does not affect snapshot behavior.

What pack outputs:

==> packing snapshot 'pyagent' → pyagent.forkd-snapshot.tar.zst
✓ wrote 22.3 MiB (512.0 MiB uncompressed; 22.9× compression) in 8.4s
  next: scp/upload, then `forkd unpack pyagent.forkd-snapshot.tar.zst` on the target host

Examples:

# Pack a snapshot with default output name
forkd pack --tag pyagent

# Pack with a custom output path
forkd pack --tag pyagent \
    --out /tmp/pyagent-v2.forkd-snapshot.tar.zst

# Pack with metadata
forkd pack --tag py-numpy \
    --description "Python 3.12 + numpy 2.0.2 warmed snapshot" \
    --base-image "python:3.12-slim" \
    --out py-numpy.forkd-snapshot.tar.zst

# Pack a chain head (bundles all ancestor links automatically)
forkd pack --tag py-pandas --out py-pandas-chain.tar.zst

`forkd push`

Pack a local snapshot on-the-fly and upload it directly to a destination URL via HTTP PUT. The pack file is built in a temp directory and removed when the upload completes (or fails). Designed for presigned PUT URLs from S3, R2, or compatible object storage.

--tag

string

required

Local snapshot tag to pack and push.

url

string

required

Destination URL (positional argument). Must be a presigned HTTP PUT URL. Generate one with:

AWS S3: aws s3 presign --method PUT s3://bucket/key.tar.zst
Cloudflare R2: equivalent via the R2 API or wrangler r2 object put

--description

string

Optional manifest description written into the pack.

--base-image

string

Optional upstream base image annotation.

Example output:

==> packing snapshot 'py-numpy' → /tmp/forkd-push-12345-pynumpy.tar.zst
    packed 22.3 MiB (22.9× compression) in 8.3s
✓ pushed 22.3 MiB in 4.1s (5.4 MiB/s)

Examples:

# Push to an S3 presigned URL
PRESIGNED_URL=$(aws s3 presign --method PUT \
    s3://my-forkd-hub/py-numpy.forkd-snapshot.tar.zst \
    --expires-in 3600)

forkd push --tag py-numpy "$PRESIGNED_URL" \
    --description "Python 3.12 + numpy warmup" \
    --base-image "python:3.12-slim"

# Push to a Cloudflare R2 public bucket
forkd push --tag pyagent "https://pub-abc123.r2.dev/pyagent.tar.zst"

`forkd pull`

Download a .forkd-snapshot.tar.zst pack from a URL or an <owner>/<name> hub short form, verify its SHA-256 checksum (when provided by the registry), and unpack it into a local snapshot tag. Equivalent to curl <url> | forkd unpack but with integrity checking and short-form name resolution built in.

Short-form name resolution

When target looks like <owner>/<name> or <owner>/<name>@<version> (no http:// or https:// prefix), forkd resolves it against the hub registry:

Fetches registry.json from FORKD_HUB_URL (default: https://raw.githubusercontent.com/deeplethe/forkd/main/registry.json).
Looks up the package <owner>/<name> and version (@<version> or latest).
Returns the download URL and expected SHA-256 from the registry entry.
Downloads the pack and verifies SHA-256 before unpacking.

A bare HTTPS URL bypasses registry lookup (no integrity check unless the registry provided the SHA-256 alongside the URL).

target

string

required

Download source (positional argument). Accepts:

HTTPS URL: direct download, no registry lookup (e.g. https://pub-abc.r2.dev/pyagent.tar.zst)
<owner>/<name>: resolves via registry to the latest version (e.g. deeplethe/python-numpy)
<owner>/<name>@<version>: resolves to a specific version (e.g. deeplethe/python-numpy@v1.0)

--tag

string

Override the local tag name. Default: the tag declared in the pack’s manifest.toml. When pulling a multi-link chain pack, --tag is rejected (ambiguous — which link gets renamed?).

--force

boolean

Overwrite an existing local snapshot of the same tag. Without --force, pull refuses to unpack over an existing tag.

--hub

string

Hub base URL for short-form target resolution. Read from the FORKD_HUB_URL environment variable when set; otherwise falls back to https://raw.githubusercontent.com/deeplethe/forkd/main/registry.json.

Examples:

# Pull the official Python + numpy snapshot from the hub
forkd pull deeplethe/python-numpy
# → resolving via https://raw.githubusercontent.com/deeplethe/forkd/main/registry.json
# ✓ downloaded 14.5 MiB (https://...)
# ✓ sha256 verified (a3f1b2c4...)
# ✓ unpacked tag 'python-numpy' at /home/user/.local/share/forkd/snapshots/python-numpy
#   next: forkd fork --tag python-numpy -n <N>

# Pull a specific version
forkd pull deeplethe/langgraph-react@v2.0

# Pull from a direct HTTPS URL
forkd pull https://pub-abc123.r2.dev/pyagent.forkd-snapshot.tar.zst

# Pull and override the local tag name
forkd pull deeplethe/python-numpy --tag my-py-snap

# Force-overwrite an existing tag
forkd pull deeplethe/python-numpy --force

# Pull from a self-hosted registry
forkd pull myorg/myagent --hub https://registry.example.com/forkd/registry.json

`forkd unpack`

Unpack a local .forkd-snapshot.tar.zst file into a local snapshot tag. Verifies every file’s SHA-256 checksum against the manifest before moving anything into the snapshot directory. Refuses on pack-format mismatch or path traversal attempts. Security model:

Every file in the archive is verified against its SHA-256 in manifest.toml before being moved to $XDG_DATA_HOME/forkd/snapshots/<tag>/.
The manifest’s declared tag field is validated against the same rules as --tag (pattern [A-Za-z0-9_][A-Za-z0-9._-]{0,63}). A malicious pack that declares tag = "../../etc/x" is rejected before any file is written.
The caller-supplied --tag is also validated, and overrides the manifest tag.
Extraction happens into a temp directory first; only on successful full verification is the temp directory atomically renamed into the snapshot store. Any error removes the temp directory.
For chain packs (v2 layout), all links are verified before any are moved. A conflict on one link does not partially unpack others.

path

required

Pack file to read (positional argument). Must exist and be a valid .forkd-snapshot.tar.zst archive.

--tag

string

Local tag to register the snapshot under. Defaults to the tag declared in the manifest. For multi-link chain packs, --tag is rejected — the manifest tags are used verbatim for each link.

--force

boolean

Overwrite an existing local snapshot of the same tag. Without --force, unpack refuses to clobber an existing tag. For chain packs, --force applies uniformly to all links.

Examples:

# Unpack a snapshot pack (uses manifest tag)
forkd unpack pyagent.forkd-snapshot.tar.zst

# Unpack and override the tag
forkd unpack pyagent.forkd-snapshot.tar.zst --tag myagent-imported

# Force-overwrite an existing tag
forkd unpack pyagent.forkd-snapshot.tar.zst --force

# Unpack a chain pack (restores all ancestor links)
forkd unpack py-pandas-chain.forkd-snapshot.tar.zst
# ✓ link 'py-base' → 'py-base' at /home/user/.local/share/forkd/snapshots/py-base
# ✓ link 'py-numpy' → 'py-numpy' at /home/user/.local/share/forkd/snapshots/py-numpy  (chain parent: py-base)
# ✓ link 'py-pandas' → 'py-pandas' at /home/user/.local/share/forkd/snapshots/py-pandas  (chain parent: py-numpy)
# ✓ unpacked 3 chain link(s), head = 'py-pandas'
#   next: forkd fork --tag py-pandas -n <N>

`forkd images`

List all local snapshots with their on-disk sizes, memory footprint, creation time, and whether a rootfs is present. Reads the snapshot directory directly — does not require the daemon to be running. Output columns:

Column	Description
`TAG`	Snapshot tag name
`SIZE`	Total on-disk size of all snapshot files (memory.bin + vmstate + snapshot.json)
`MEMORY`	Size of `memory.bin` alone (the CoW source the children map)
`CREATED`	Age of the snapshot (human-relative, e.g. `3d ago`)
`ROOTFS`	`yes` if a rootfs file is referenced in `snapshot.json`; `—` otherwise

No flags. If no local snapshots exist, prints a hint to run forkd snapshot or forkd pull. Example output:

forkd images

  TAG               SIZE        MEMORY      CREATED     ROOTFS
  py-base          531.2 MiB   512.0 MiB   2d ago      yes
  py-numpy         393.8 MiB   393.2 MiB   1d ago      —
  py-pandas        421.0 MiB   420.4 MiB   6h ago      —
  pyagent          518.4 MiB   512.0 MiB   3d ago      yes

  4 snapshots · 1.8 GiB total

Combine with forkd where to locate snapshot files directly:

ls "$(forkd where)/snapshots/pyagent"
# memory.bin  vmstate  snapshot.json

CLI

REST API

SDKs

forkd pack, push, pull, unpack, and images commands

`forkd pack`

`forkd push`

`forkd pull`

Short-form name resolution

`forkd unpack`

`forkd images`

Build docs developers (and LLMs) love

CLI

REST API

SDKs

Documentation Index

​forkd pack

​forkd push

​forkd pull

​Short-form name resolution

​forkd unpack

​forkd images

Build docs developers (and LLMs) love

`forkd pack`

`forkd push`

`forkd pull`

Short-form name resolution

`forkd unpack`

`forkd images`