Install MiniBox on Linux: Binaries, PATH, and Environment

MiniBox ships as two binaries: minibox (the CLI) and miniboxd (the daemon). Both are compiled from the same Go source. This page covers three installation methods, PATH setup, and all environment variables for the daemon and CLI.

Prerequisites

Linux — MiniBox uses Linux-specific features (namespaces, overlayfs, cgroups v2, iptables) and does not run on macOS or Windows
Kernel 5.11+ — recommended for full cgroups v2 support; earlier kernels with cgroups v2 enabled may work
Go 1.21+ — required only if building from source; pre-built binaries do not need Go
Root or sudo access — the miniboxd daemon must run as root for overlayfs mounts and network setup
overlayfs support — verify with grep overlay /proc/filesystems; most modern distros include it

The minibox CLI does not require root. Only the miniboxd daemon needs elevated privileges. Run the daemon with sudo -E to preserve your environment variables (including MINIBOX_DATA_ROOT).

Install Methods

User Install (Recommended)
System Install
Build From Source

Installs minibox and miniboxd to ~/.local/bin. No system-wide changes.

git clone https://github.com/chaitu426/minibox.git
cd minibox
make install-user

Add ~/.local/bin to your PATH if it is not already present:

export PATH="$HOME/.local/bin:$PATH"

To persist this across shell sessions, add it to your shell profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Use sudo -E miniboxd to start the daemon so that your MINIBOX_DATA_ROOT and other env vars are inherited by the root process.

Installs minibox and miniboxd to /usr/local/bin, making them available system-wide for all users.

git clone https://github.com/chaitu426/minibox.git
cd minibox
make install-system

No PATH changes are needed — /usr/local/bin is on the default PATH for most Linux distributions.

A system install writes to /usr/local/bin and may require sudo. The binaries will be owned by root. Uninstall by removing /usr/local/bin/minibox and /usr/local/bin/miniboxd manually.

Build the binaries locally into the ./bin directory without installing them.

git clone https://github.com/chaitu426/minibox.git
cd minibox
make build

This produces:

bin/minibox-cli     # rename or alias to 'minibox'
bin/minibox-daemon  # rename or alias to 'miniboxd'

Add the bin/ directory to your PATH for the current session:

export PATH="$PWD/bin:$PATH"

Or build and run the binaries directly:

go build -o bin/minibox ./cmd/cli
go build -o bin/miniboxd ./cmd/daemon
./bin/miniboxd &
./bin/minibox ping

Verify the Installation

Start the daemon in one terminal:

sudo -E miniboxd

In a second terminal, verify connectivity:

minibox ping
# Daemon is running

List available images (empty on a fresh install):

minibox images

Environment Variables

Daemon Environment Variables (`miniboxd`)

Set these before starting miniboxd. When using sudo -E, they are inherited from your shell.

Variable	Default	Description
`MINIBOX_DATA_ROOT`	`/var/lib/minibox`	Root directory for all persistent data: images, containers, blobs, layers, and state. Set this to a path you own (e.g. `$HOME/.minibox-data`) to avoid writing to system directories.
`MINIBOX_HTTP_ADDR`	`127.0.0.1:8080`	Bind address for the daemon HTTP API. Defaults to loopback only. Set to `:8080` only if you intend to expose the API on all interfaces — never do this without also setting `MINIBOX_API_TOKEN`.
`MINIBOX_API_TOKEN`	(none)	If set, every API request must include `Authorization: Bearer <token>` or the `X-API-Token` header. Set the same value on the CLI side to authenticate.
`MINIBOX_BUILD_PREFIXES`	`/home,/tmp,/var/lib/minibox,/root,/srv,/opt,/usr/local/src`	Comma-separated list of filesystem roots from which build context directories are allowed. The daemon rejects build requests whose context path is not under one of these prefixes.
`MINIBOX_SUBUID_BASE`	`100000`	First host UID/GID used for user-namespace mapping. Container UID 0 maps to this host UID, not to root (UID 0).
`MINIBOX_SUBUID_COUNT`	`65536`	Size of the UID/GID map for user-namespace mapping.
`MINIBOX_INDEX_ON_STARTUP`	`1`	Set to `0` to skip blob indexing at daemon startup. Useful for fast restarts when you have many blobs. Indexing will still happen lazily as needed.
`MINIBOX_BRIDGE_ON_STARTUP`	`1`	Set to `0` to skip `minibox0` bridge setup at daemon startup. The bridge will be created lazily on the first container run that needs networking.
`MINIBOX_INDEX_LAYERS`	`1`	Set to `0` to skip layer indexing during build finalization. Speeds up the final step of a build when you have many layers.
`MINIBOX_ENCRYPTION_KEY`	(none)	If set, `state.json` container metadata is encrypted at rest using AES-256-GCM. Expected value is a 32-byte hex string (64 hex characters).

CLI Environment Variables (`minibox`)

Variable	Default	Description
`MINIBOX_API`	`http://127.0.0.1:8080`	Base URL of the daemon API. Change this if you run `miniboxd` on a non-default address or port.
`MINIBOX_API_TOKEN`	(none)	Bearer token sent with every API request. Must match the token the daemon was started with.
`NO_COLOR`	(none)	Set to any non-empty value to disable all ANSI color output in the CLI.
`MINIBOX_PLAIN`	(none)	Set to any non-empty value to disable color output. Equivalent to `NO_COLOR` for MiniBox-specific output.

Recommended Data Root Setup

By default, miniboxd stores all data in /var/lib/minibox, which requires root ownership. For local development, point the data root at a directory you own:

export MINIBOX_DATA_ROOT="$HOME/.minibox-data"
sudo -E miniboxd

Add the export to your profile so it persists:

echo 'export MINIBOX_DATA_ROOT="$HOME/.minibox-data"' >> ~/.bashrc
source ~/.bashrc

To clean up all images, containers, and blobs:

minibox system prune
# or, to also clear the DAG build cache:
minibox system prune --build-cache

Using an API Token

To secure the daemon API, generate a token and export it before starting miniboxd:

export MINIBOX_API_TOKEN="$(openssl rand -hex 16)"
sudo -E miniboxd &

# In a second terminal, export the same token for the CLI:
export MINIBOX_API_TOKEN="<your-token>"
minibox ping
# Daemon is running

Without MINIBOX_API_TOKEN, anyone who can reach the daemon’s HTTP address can run containers as root. Always set a token if MINIBOX_HTTP_ADDR is set to anything other than 127.0.0.1:8080.

Next Steps

Quickstart

Build and run your first container now that MiniBox is installed.

Introduction

Learn the full architecture: namespaces, OCI storage, DAG builds, and networking.

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Install MiniBox on Linux: Binaries, PATH, and Environment

Prerequisites

Install Methods

Verify the Installation

Environment Variables

Daemon Environment Variables (`miniboxd`)

CLI Environment Variables (`minibox`)

Recommended Data Root Setup

Using an API Token

Next Steps

Quickstart

Introduction

Build docs developers (and LLMs) love

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Documentation Index

​Prerequisites

​Install Methods

​Verify the Installation

​Environment Variables

​Daemon Environment Variables (miniboxd)

​CLI Environment Variables (minibox)

​Recommended Data Root Setup

​Using an API Token

​Next Steps

Quickstart

Introduction

Build docs developers (and LLMs) love

Prerequisites

Install Methods

Verify the Installation

Environment Variables

Daemon Environment Variables (`miniboxd`)

CLI Environment Variables (`minibox`)

Recommended Data Root Setup

Using an API Token

Next Steps