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.

These endpoints manage the local OCI image store maintained by miniboxd. They cover listing, pulling from registries, exporting to archives, importing from archives, removing images, and pruning unused blobs. All examples use curl with an Authorization header — omit it when MINIBOX_API_TOKEN is not set.

​
GET /images

List all named images registered in the daemon’s local index.json. 
GET /images

​
Response

​
body
array
JSON array of image objects.
curl http://127.0.0.1:8080/images \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"
Example response: 
[
  {"name": "myapp", "size_bytes": 12345678},
  {"name": "redis-base", "size_bytes": 8765432}
]

​
POST /images/pull

Pull an OCI image from a container registry (defaults to Docker Hub). The image is stored in DataRoot/base_layers/<image_tag> and registered in index.json. 
POST /images/pull?image=<image-name>
​
image
string
required
Image reference to pull. Supports standard OCI reference format (e.g. alpine, alpine:3.18, library/nginx:latest). Multi-arch manifest lists are automatically resolved to linux/amd64.

​
Response

200 OK — streamed plain text pull progress using Transfer-Encoding: chunked. Each line is prefixed with [pull]. Errors are reported as [error] pull failed: .... 
curl -X POST "http://127.0.0.1:8080/images/pull?image=alpine:3.18" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /images/save

Export a locally stored image to a tar archive on the daemon host filesystem. 
POST /images/save?image=<name>&path=<output-path>
​
image
string
required
Name of the image to export. Must exist in the local index.
​
path
string
required
Absolute path on the daemon host where the tar archive will be written. The file is created or overwritten.

​
Response

200 OK — Saved image <name> to <path>\n 
curl -X POST "http://127.0.0.1:8080/images/save?image=myapp&path=/tmp/myapp.tar" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
Archive layout

The produced tar is a minibox-specific archive (not Docker-compatible):
FileContents
meta.json{"image": "<name>", "manifest_digest": "sha256:..."}
blobs/sha256/<digest>OCI manifest JSON blob
blobs/sha256/<digest>OCI config JSON blob
blobs/sha256/<digest>Each layer (gzip-compressed tar)

​
POST /images/load

Import an image tar archive previously created by POST /images/save. 
POST /images/load?path=<input-path>
​
path
string
required
Absolute path on the daemon host to the tar archive to import.

​
Response

200 OK — Loaded image <name> from <path>\n 
curl -X POST "http://127.0.0.1:8080/images/load?path=/tmp/myapp.tar" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"
load extracts the archive into DataRoot, reads meta.json, and upserts the image entry into index.json. Loading the same image twice is idempotent — blobs are content-addressed by their SHA256 digest.

​
POST /images/remove

Remove a named image from the local index. 
POST /images/remove?image=<name>
​
image
string
required
Image name exactly as listed by GET /images.

​
Response

200 OK — Image <name> removed\n 404 Not Found — if the image name is not in the index. 
curl -X POST "http://127.0.0.1:8080/images/remove?image=myapp" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"
images/remove removes the image’s entry from index.json but does not delete the underlying blobs from blobs/sha256/. Orphaned blobs are cleaned up by POST /system/prune.

​
POST /system/prune

Garbage-collect unused blobs, clean up stale lazy FUSE mounts, remove extracted layer directories, and delete temporary files under DataRoot. 
POST /system/prune?build_cache=<0|1>
​
build_cache
string
default:"0"
Set to 1 to also remove the DAG build cache under DataRoot/layers/. This forces a full image rebuild the next time POST /containers/build is called.

​
Response

​
body
object
JSON prune report describing what was removed.
# Standard prune
curl -X POST "http://127.0.0.1:8080/system/prune" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

# Prune + clear build cache
curl -X POST "http://127.0.0.1:8080/system/prune?build_cache=1" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"
system/prune with build_cache=1 deletes all content-addressed layer directories under DataRoot/layers/. The next build will re-execute every block from scratch, including downloading base images and running all RUN instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us