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.

The minibox system namespace contains maintenance commands for cleaning up unused data. This page also covers the miniboxd daemon itself — how to start it, check its version, configure it via environment variables, and secure it with an API token.

​
system prune

Remove orphaned blobs, tear down stale lazy FUSE mounts, clean extracted layers, and delete temporary files under DataRoot. 
minibox system prune [--build-cache]
​
--build-cache
boolean
default:"false"
Also clear the DAG build cache under DataRoot/layers/. This forces a full image rebuild the next time minibox build is run. Without this flag, cached block layers are preserved.
# Standard prune: blobs, stale mounts, tmp
minibox system prune

# Prune + clear DAG build cache (forces full rebuild)
minibox system prune --build-cache

​
What prune removes

ResourceRemoved by pruneRemoved by prune --build-cache
Orphaned blobs in blobs/sha256/ not referenced by index.json✅✅
Stale lazy FUSE mounts✅✅
Extracted layer directories under extracted/✅✅
Temporary files under DataRoot/tmp/✅✅
DAG block layer cache under DataRoot/layers/❌✅
system prune does not remove named volumes under DataRoot/volumes/ or active container directories. To fully reset the data root, use the provided scripts/clean-data.sh script.
Run system prune regularly to reclaim disk space. The --build-cache flag is useful when you want to verify that your MiniBox file produces a correct image from scratch, independent of any cached intermediate layers.

​
miniboxd daemon

miniboxd is the daemon binary that runs the HTTP API and the container runtime backend. It requires root privileges for overlay mounts, bridge networking, and iptables rules.

​
Start

# Recommended: preserve environment variables
sudo -E miniboxd

# With explicit data root
MINIBOX_DATA_ROOT=/opt/minibox sudo -E miniboxd
Default listen address: 127.0.0.1:8080 (localhost only).

​
Version

miniboxd --version

​
Daemon Environment Variables

Configure miniboxd by exporting these variables before starting the daemon. Because sudo strips the environment by default, use sudo -E or set variables in /etc/environment.
​
MINIBOX_DATA_ROOT
string
default:"/var/lib/minibox"
Root directory for all minibox data: images, blobs, layers, containers, volumes, and state. Set this to a non-system path during development to keep data isolated.
export MINIBOX_DATA_ROOT="$HOME/.minibox-data"
​
MINIBOX_HTTP_ADDR
string
default:"127.0.0.1:8080"
TCP address the daemon listens on. Use :8080 only if you intentionally want to expose the API on all network interfaces. For local use, keep the default loopback binding.
export MINIBOX_HTTP_ADDR="127.0.0.1:9090"
​
MINIBOX_API_TOKEN
string
When set, every API request must present this token as Authorization: Bearer <token> or X-API-Token: <token>. Requests without the token receive a 401 Unauthorized response.
export MINIBOX_API_TOKEN="$(openssl rand -hex 16)"
​
MINIBOX_BUILD_PREFIXES
string
Comma-separated list of allowed build context directory roots. The daemon rejects POST /containers/build requests whose context_path does not fall under one of these prefixes. Prevents arbitrary host path access via the build API.
export MINIBOX_BUILD_PREFIXES="/home/user/projects,/opt/builds"
​
MINIBOX_SUBUID_BASE
integer
default:"100000"
First host UID/GID to use for user-namespace ID mapping.
​
MINIBOX_SUBUID_COUNT
integer
default:"65536"
Size of the UID/GID map range for user-namespace mapping.
​
MINIBOX_INDEX_ON_STARTUP
integer
default:"1"
Set to 0 to skip blob indexing at daemon startup. Blob indexing is deferred to the first operation that requires it. Reduces startup latency significantly on hosts with large blob stores.
export MINIBOX_INDEX_ON_STARTUP=0
​
MINIBOX_BRIDGE_ON_STARTUP
integer
default:"1"
Set to 0 to skip bridge (minibox0) setup at daemon startup. The bridge is created lazily when the first container requires networking. Makes startup near-instant on hosts where bridge creation is slow.
export MINIBOX_BRIDGE_ON_STARTUP=0
​
MINIBOX_INDEX_LAYERS
integer
default:"1"
Set to 0 to disable layer indexing during build finalization. Speeds up the finalize step for large layer sets.
​
MINIBOX_ENCRYPTION_KEY
string
32-byte hex string used to encrypt container state metadata at rest. When set, state.json entries are AES-encrypted before being written to disk. Leave unset to store state as plain JSON (the default).

​
API Token Setup

1

Generate a random token

export MINIBOX_API_TOKEN="$(openssl rand -hex 16)"
echo "Token: $MINIBOX_API_TOKEN"
2

Start the daemon with the token

MINIBOX_API_TOKEN="$MINIBOX_API_TOKEN" sudo -E miniboxd
The daemon will reject any request missing the correct Authorization header.
3

Export the token for the CLI

export MINIBOX_API_TOKEN="your-token-here"
The CLI reads MINIBOX_API_TOKEN and attaches it to every request automatically.
4

Verify the secured connection

minibox ping
# Daemon is running
A successful ping confirms the CLI is sending the correct token.
Without MINIBOX_API_TOKEN, the API is unauthenticated and accessible to any process on the host that can reach 127.0.0.1:8080. Always set a token in multi-user environments or when MINIBOX_HTTP_ADDR is exposed beyond loopback.

Build docs developers (and LLMs) love

Get started for freeTalk to us