Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chaitu426/minibox/llms.txt

Use this file to discover all available pages before exploring further.

MiniBox stores images in an OCI-like blob store under MINIBOX_DATA_ROOT (default /var/lib/minibox). Each image is referenced by name in index.json and its content lives as content-addressed blobs under blobs/sha256/. This page covers every image management command and the underlying storage layout.

​
Listing Images

minibox images
Prints a table of all images known to the local index.json, including name, manifest digest (short-form), and on-disk size. 
minibox images --json
Emits a JSON array for scripting or CI pipelines. 
[
  {
    "name": "myapp",
    "digest": "sha256:a1b2c3d4...",
    "size": 48234567
  },
  {
    "name": "redis:latest",
    "digest": "sha256:ff00aa11...",
    "size": 12048576
  }
]
Pipe --json output through jq to filter or format: minibox images --json | jq '.[].name'

​
Removing an Image

minibox rmi <image>
Removes the named image reference from index.json. Orphaned blobs (manifests, configs, and layers no longer referenced by any image) are not deleted immediately — run minibox system prune to reclaim their disk space. 
minibox rmi myapp
minibox rmi redis:latest
rmi and system prune are separate operations by design. You can remove an image reference and still recover it from its blobs until you prune.

​
Saving an Image to a Tar Archive

minibox save <image> <output.tar>
Packs the named image into a portable tar archive. The archive layout is: 
output.tar
├── meta.json               # image name + manifest digest
└── blobs/
    └── sha256/
        ├── <manifest-digest>         # OCI manifest JSON
        ├── <manifest-digest>.index.json  # index entry (if present)
        ├── <config-digest>           # OCI image config JSON
        └── <layer-digest>            # gzipped tar layer(s)
meta.json contains just enough metadata for minibox load to reconstruct the index.json entry: 
{
  "image": "myapp",
  "manifest_digest": "sha256:a1b2c3d4..."
}
The minibox save format is a MiniBox-native archive of the internal OCI-like blob store. It is not compatible with docker save / docker load. Do not attempt to load a MiniBox archive with Docker or vice-versa.

​
Example: export and copy to another host

# On the source host
minibox save myapp /tmp/myapp.tar
scp /tmp/myapp.tar user@target:/tmp/

# On the target host
minibox load /tmp/myapp.tar
minibox images

​
Loading an Image from a Tar Archive

minibox load <input.tar>
Extracts all blobs from the archive into DataRoot/blobs/sha256/, reads meta.json, and upserts the image reference into index.json. If the image name already exists in the index it is updated to point to the loaded manifest digest. 
minibox load /tmp/myapp.tar
# → image "myapp" loaded
minibox images

​
OCI Storage Layout

All image data lives under MINIBOX_DATA_ROOT. The layout mirrors the OCI Image Layout Specification with a few MiniBox-specific additions. 
/var/lib/minibox/
├── index.json                        # image name → manifest digest registry
├── blobs/
│   └── sha256/
│       ├── <manifest-digest>         # OCIManifest JSON (points to config + layers)
│       ├── <config-digest>           # OCIConfig JSON (cmd/env/workdir/labels)
│       └── <layer-digest>            # gzipped tar layer blob
├── layers/                           # DAG build cache (upper-dir snapshots)
├── base_layers/                      # pulled base image rootfs cache
├── containers/
│   └── <container-id>/
│       ├── upper/                    # container-specific overlay upper dir
│       ├── work/                     # overlay work dir
│       ├── rootfs/                   # merged container filesystem
│       └── container.log            # stdout/stderr log
├── volumes/                          # named persistent volumes (db_mode)
├── lazy/                             # FUSE-mounted lazy layer dirs
├── cache/                            # lazy-layer read cache
├── extracted/                        # fully-extracted layer cache
├── tmp/                              # in-progress build scratch space
└── state.json                        # runtime container state

​
System Prune

system prune performs garbage collection across the entire data root. It removes:
  • Orphaned blobs — blobs in blobs/sha256/ not referenced by any manifest in index.json.
  • Dangling FUSE mounts — stale lazy-layer mount points in lazy/ and their associated cache/ entries.
  • Dangling extracted layers — orphaned directories in extracted/.
  • Incomplete tmp layers — the entire tmp/ directory left by interrupted builds.
minibox system prune
The command prints a summary report: 
System Prune Completed:
  - Active FUSE mounts killed: 1
  - Orphaned blobs removed:   4
  - Disk space recovered:     128.4 MB

​
Clearing the Build Cache

The DAG build cache (layers/) is separate from the OCI blob store. Removing an image with rmi does not clear the build cache. To force a full rebuild of all MiniBox images: 
minibox system prune --build-cache
This deletes every directory under DataRoot/layers/ and reports the additional space reclaimed: 
System Prune Completed:
  - Active FUSE mounts killed: 0
  - Orphaned blobs removed:   0
  - Disk space recovered:     0 B
  - Build cache entries removed: 23
  - Build cache recovered:       512.0 MB
After --build-cache, the next minibox build for any image will re-execute all DAG blocks from scratch. Subsequent builds will repopulate the cache normally.

Build docs developers (and LLMs) love

Get started for freeTalk to us