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 CLI is a thin HTTP client that talks to the miniboxd daemon over a local REST API. Every command — from building images to stopping containers — translates to one or more HTTP requests. You must start miniboxd before running any command except ping.

​
Installation

1

Build the binaries

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

Install to user PATH (recommended)

make install-user
export PATH="$HOME/.local/bin:$PATH"
This installs both minibox (CLI) and miniboxd (daemon) into ~/.local/bin.
3

Start the daemon

sudo -E miniboxd
The daemon requires root for networking (bridge/veth/iptables) and overlay mounts.
4

Verify connectivity

minibox ping
# Daemon is running

​
HTTP Client Architecture

The CLI contains no container logic of its own. All operations are delegated to miniboxd via HTTP. The default base URL is http://127.0.0.1:8080.
Every CLI command maps directly to a daemon API endpoint:
CLI commandHTTP request
minibox pingGET /ping
minibox buildPOST /containers/build
minibox runPOST /containers/run
minibox psGET /containers
minibox logsGET /containers/logs
minibox execPOST /containers/exec
minibox stopPOST /containers/stop
minibox killPOST /containers/kill
minibox startPOST /containers/start
minibox rmPOST /containers/remove
minibox statsGET /containers/stats
minibox imagesGET /images
minibox rmiPOST /images/remove
minibox savePOST /images/save
minibox loadPOST /images/load
minibox system prunePOST /system/prune

​
CLI Environment Variables

​
MINIBOX_API
string
default:"http://127.0.0.1:8080"
Base URL of the miniboxd daemon. Change this if you run the daemon on a non-default port or address.
export MINIBOX_API="http://127.0.0.1:9090"
​
MINIBOX_API_TOKEN
string
Bearer token sent to the daemon when MINIBOX_API_TOKEN is set on the daemon side. The CLI reads this variable and attaches it as Authorization: Bearer <token> on every request.
export MINIBOX_API_TOKEN="$(openssl rand -hex 16)"

​
Command Summary

All 17 commands available in the minibox CLI:
CommandDescription
pingCheck daemon connectivity — prints Daemon is running
buildBuild an image from a MiniBox file and context directory
runRun a container from a local image
psList containers (running by default, -a for all)
statsLive cgroup resource stats for one container
logsPrint stdout/stderr log for a container
execRun a command inside a running container via namespace entry
stopSend SIGTERM (then SIGKILL on timeout) to a container
killSend SIGKILL immediately to a container
rmRemove a container record and its data directory
imagesList local images from the daemon index
rmiRemove an image from the local index
saveExport an image to a tar archive
loadImport an image from a tar archive
composeMulti-container orchestration (up/down/ps/logs/build/start/stop/restart)
system pruneGarbage-collect orphaned blobs, layers, and stale mounts
db runRun a database container with production-safe defaults

​
Container ID Format

Container IDs are 8 hexadecimal characters (e.g. a1b2c3d4). They are generated randomly at container creation time. 
# The ID is printed on run
minibox run -d myapp
# a1b2c3d4

# Use it for all subsequent commands
minibox logs a1b2c3d4
minibox stats a1b2c3d4
minibox stop a1b2c3d4
minibox rm a1b2c3d4
Run minibox ps at any time to list all running containers and their IDs, ports, health status, and exit codes.

​
JSON Output

Several commands support --json for scripting and automation: 
# Machine-readable container list
minibox ps --json

# Machine-readable image list
minibox images --json
Output mode can also be controlled with the NO_COLOR or MINIBOX_PLAIN environment variables to suppress ANSI formatting in plain-text output.

​
Typical Session

# Terminal 1 — start daemon
sudo -E miniboxd

# Terminal 2 — use the CLI
export PATH="$PWD/bin:$PATH"

minibox ping
minibox build -t demo .
minibox run -d -p 3001:3000 demo
minibox ps
minibox logs <container-id>
minibox stop <container-id>
minibox rm <container-id>

​
With API token authentication

export MINIBOX_API_TOKEN="$(openssl rand -hex 16)"
MINIBOX_API_TOKEN="$MINIBOX_API_TOKEN" sudo -E miniboxd &
minibox ping   # token automatically attached

​
Explore Commands

Build & Run Commands

ping, build, run, ps, logs, exec, stop, kill, rm, stats, db run

Image Commands

images, rmi, save, load

Compose Commands

compose up, down, ps, logs, build, start, stop, restart

System Commands

system prune, miniboxd daemon and env vars

Build docs developers (and LLMs) love

Get started for freeTalk to us