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 is configured exclusively through environment variables — there is no configuration file. Daemon variables are read at startup by internal/config/config.go. CLI variables are read at invocation time. This page documents every supported variable with its type, default, and recommended usage.

​
Daemon Variables (miniboxd)

​
MINIBOX_DATA_ROOT
string
default:"/var/lib/minibox"
Filesystem path where miniboxd stores all persistent state: OCI blobs, container overlay filesystems, state.json, volumes, and build cache.
export MINIBOX_DATA_ROOT="$HOME/.minibox-data"
sudo -E miniboxd
Never point MINIBOX_DATA_ROOT at a system directory such as /, /home, /etc, or /var. The daemon will refuse to delete protected paths, but an incorrect data root can still cause confusion. Use a dedicated directory.
​
MINIBOX_HTTP_ADDR
string
default:"127.0.0.1:8080"
TCP host:port the daemon HTTP API listens on. The default binds to loopback only. Change this if you need the daemon reachable from other hosts, and pair it with MINIBOX_API_TOKEN to protect the endpoint.
export MINIBOX_HTTP_ADDR="0.0.0.0:9090"
​
MINIBOX_API_TOKEN
string
default:"(unset — auth disabled)"
When set, every incoming API request must present the token as either:
  • Authorization: Bearer <token> header, or
  • X-API-Token: <token> header.
Requests missing a valid token receive 401 Unauthorized. Set the same value on both the daemon and the CLI.
# Generate a strong random token
export MINIBOX_API_TOKEN="$(openssl rand -hex 32)"
​
MINIBOX_BUILD_PREFIXES
string (comma-separated paths)
Comma-separated list of filesystem path prefixes that are allowed as build context directories. Any build context submitted to POST /containers/build must resolve to a path under one of these prefixes. This prevents path-traversal attacks from reaching arbitrary host directories.
export MINIBOX_BUILD_PREFIXES="/home,/srv/projects,/opt/src"
​
MINIBOX_SUBUID_BASE
integer
default:"100000"
First host UID/GID used for user-namespace ID mapping. Container UID 0 maps to this UID on the host rather than to root (UID 0), following the rootless-container convention.
export MINIBOX_SUBUID_BASE=200000
​
MINIBOX_SUBUID_COUNT
integer
default:"65536"
The size of the [container → host] UID/GID map. Must be large enough to cover all UIDs used inside container images. The default (65536) covers the full 16-bit range.
export MINIBOX_SUBUID_COUNT=65536
​
MINIBOX_INDEX_ON_STARTUP
0 | 1
default:"1"
When 1, the daemon walks DataRoot/blobs/sha256 on startup to index all known blobs. Set to 0 to skip this scan and reach a ready state faster, at the cost of deferred index consistency.
export MINIBOX_INDEX_ON_STARTUP=0   # faster daemon start
​
MINIBOX_BRIDGE_ON_STARTUP
0 | 1
default:"1"
When 1, the daemon creates the minibox0 bridge and configures iptables NAT at startup. When 0, the bridge is created lazily the first time a container with port mappings is started.
export MINIBOX_BRIDGE_ON_STARTUP=0  # defer bridge setup until first container
​
MINIBOX_INDEX_LAYERS
0 | 1
default:"1"
When 1, layer blobs are indexed after each build finalization. Set to 0 to disable layer indexing for faster build finalization at the cost of deferred index updates.
export MINIBOX_INDEX_LAYERS=0       # faster build finalize
​
MINIBOX_ENCRYPTION_KEY
string (32-byte hex)
default:"(unset — encryption disabled)"
When set, must be a 32-byte value encoded as a 64-character hexadecimal string. Used to encrypt container metadata at rest. Leave unset for plaintext storage in trusted environments.
export MINIBOX_ENCRYPTION_KEY="$(openssl rand -hex 32)"

​
CLI Variables (minibox)

​
MINIBOX_API
string
default:"http://127.0.0.1:8080"
Base URL of the miniboxd daemon API. Override when the daemon is bound to a non-default address or port.
export MINIBOX_API="http://127.0.0.1:9090"
minibox ps
​
MINIBOX_API_TOKEN
string
default:"(unset)"
Token sent by the CLI with every API request. Must match the token configured on the daemon. The CLI sends the value as Authorization: Bearer <token>.
export MINIBOX_API_TOKEN="<same-token-as-daemon>"
​
NO_COLOR
string (any non-empty value)
Disables ANSI color codes in all CLI output. This is the standard NO_COLOR convention recognized by many CLI tools.
NO_COLOR=1 minibox ps
​
MINIBOX_PLAIN
string (any non-empty value)
Minibox-specific plain output mode. Disables colors and decorative formatting, suitable for log aggregation or piping output to other tools.
MINIBOX_PLAIN=1 minibox images

​
Recipes

​
Safe data root setup

# Create an isolated directory for all minibox state
mkdir -p "$HOME/.minibox-data"
export MINIBOX_DATA_ROOT="$HOME/.minibox-data"

# Start the daemon (root required for networking + overlayfs)
sudo -E miniboxd

​
Generating and wiring an API token

# Generate a cryptographically strong 256-bit token
TOKEN="$(openssl rand -hex 32)"

# Start the daemon with the token
MINIBOX_API_TOKEN="$TOKEN" sudo -E miniboxd &

# Export the token for the CLI in the same shell session
export MINIBOX_API_TOKEN="$TOKEN"

# Verify connectivity
minibox ping

​
Startup performance tuning

By default, the daemon indexes blobs and brings up the network bridge at startup. In environments where startup latency matters (e.g., CI ephemeral runners), you can defer both: 
export MINIBOX_INDEX_ON_STARTUP=0
export MINIBOX_BRIDGE_ON_STARTUP=0
export MINIBOX_INDEX_LAYERS=0
sudo -E miniboxd
With MINIBOX_INDEX_ON_STARTUP=0 the daemon starts faster but minibox images may show a stale list until a build or explicit index operation occurs. Suitable for CI pipelines that always build before querying.

Build docs developers (and LLMs) love

Get started for freeTalk to us