minibox Build, Run, and Container Lifecycle Commands

These commands cover the full container lifecycle: checking daemon health, building images, running containers, inspecting them, executing commands inside, and tearing them down. All commands communicate with miniboxd over HTTP.

ping

Check that the daemon is reachable and responding.

minibox ping

Output: Daemon is running

ping is the only command you can safely run when the daemon is not yet started — it simply tells you whether it is up. A connection error means miniboxd is not running or MINIBOX_API points to the wrong address.

build

Build an OCI-compatible image from a directory containing a MiniBox file.

minibox build -t <image-name> [context-directory]

The context directory defaults to . (current directory) when omitted.

-t

string

required

Image name (tag) to assign to the built image. Used to reference the image in run, rmi, save, etc.

context-directory

string

default:"."

Path to the build context. The directory must contain a MiniBox file. The daemon validates this path against MINIBOX_BUILD_PREFIXES.

# Build from current directory, tag as "myapp"
minibox build -t myapp .

# Build from a specific path
minibox build -t webserver /home/user/my-project

The daemon enforces that the build context directory falls under one of the paths listed in the MINIBOX_BUILD_PREFIXES environment variable. Build requests with contexts outside those prefixes are rejected with a 400 Bad Request.

Health check support

MiniBox files support a basic HEALTHCHECK directive:

HEALTHCHECK --interval=30 /bin/sh -c "wget -qO- http://127.0.0.1:3000/health || exit 1"

The health metadata is stored as OCI config labels (mini.healthcheck.cmd, mini.healthcheck.interval) and surfaced as starting, healthy, or unhealthy in the HEALTH column of ps.

run

Run a command in a new container from a local image.

minibox run [-d] [-m <memoryMB>] [-c <cpuMax>] [-p <host:container>] <image> [command...]

-d

boolean

default:"false"

Detached mode. The container starts in the background; only the container ID is printed to stdout.

-m

integer

Memory limit in megabytes. Written to the container cgroup’s memory.max.

-c

integer

CPU quota limit in cgroup v2 cpu.max format (e.g. 50000 for 50% of one CPU).

-p

string

Port mapping in host:container format (e.g. -p 8080:80). Repeat the flag for multiple mappings. The daemon programs iptables DNAT rules for each mapping.

image

string

required

Name of a locally built image (as tagged with minibox build -t).

command

string[]

Override the image default command. If the image has an Entrypoint, the provided command is appended to it. If omitted, the image’s Entrypoint + CMD is used.

# Interactive foreground run
minibox run alpine /bin/sh

# Detached
minibox run -d myapp

# Memory limit 512 MB, map host port 9000 → container port 80
minibox run -m 512 -p 9000:80 myapp

# Custom command override
minibox run alpine ls -la /

# Multiple port mappings
minibox run -d -p 8080:80 -p 4430:443 myapp

ps

List containers managed by the daemon.

minibox ps [-a] [--json]

-a

boolean

default:"false"

Include stopped and exited containers. Without -a, only running containers are shown.

--json

boolean

default:"false"

Output the container list as JSON instead of the default table.

# Running containers only
minibox ps

# All containers including stopped
minibox ps -a

# Machine-readable JSON
minibox ps --json

The table columns are: ID, IMAGE, COMMAND, STATUS, HEALTH, EXIT, PORTS, CREATED.

logs

Fetch the stdout/stderr log for a container.

minibox logs <containerID>

containerID

string

required

The 8-character hex container ID returned by run or ps.

minibox logs a1b2c3d4

Logs are stored at DataRoot/containers/<id>/container.log and served as plain text.

exec

Run a command inside a running container by entering its Linux namespaces.

minibox exec [-it] <containerID> <cmd...>

-it

boolean

default:"false"

Attach stdin, stdout, and stderr to your terminal for interactive use. Requires nsenter from util-linux to be installed on the host.

containerID

string

required

The 8-character hex ID of a running container.

cmd

string[]

required

Command and arguments to execute inside the container’s namespaces.

# Non-interactive: list files
minibox exec a1b2c3d4 ls -la /

# Interactive shell
minibox exec -it a1b2c3d4 /bin/sh

# Run a one-off command
minibox exec a1b2c3d4 cat /etc/os-release

exec requires the container to be in running status. It uses nsenter to enter the container’s PID, mount, UTS, and network namespaces.

stop

Stop a running container gracefully by sending SIGTERM, then SIGKILL if the timeout expires.

minibox stop [-t <seconds>] <containerID>

-t

integer

default:"10"

Timeout in seconds to wait after SIGTERM before sending SIGKILL.

containerID

string

required

The 8-character hex ID of a running container.

# Default 10-second graceful stop
minibox stop a1b2c3d4

# Custom 30-second timeout
minibox stop -t 30 a1b2c3d4

# Immediate: SIGTERM then SIGKILL after 0 seconds
minibox stop -t 0 a1b2c3d4

kill

Force-kill a container immediately with SIGKILL.

minibox kill <containerID>

containerID

string

required

The 8-character hex ID of a running container.

minibox kill a1b2c3d4

The container’s exit code is recorded as 137 (128 + SIGKILL signal number 9).

rm

Remove a stopped container: deletes its state entry and its directory under DataRoot/containers/<id>/.

minibox rm <containerID>

containerID

string

required

The 8-character hex container ID to remove.

minibox rm a1b2c3d4

rm permanently deletes container data including logs. Stop the container first with minibox stop before removing it.

stats

Display live cgroup resource stats for a running container. Refreshes once per second. Press Ctrl+C to exit.

minibox stats <containerID>

containerID

string

required

The 8-character hex ID of a running container.

minibox stats a1b2c3d4

Stats include: memory usage, CPU usage, PID count, block I/O, and host veth network counters.

db run

Run a database container with production-friendly defaults. db run is a superset of run that configures the container for database workloads: persistent named volumes, larger /dev/shm, higher I/O priority, and OOM protection.

minibox db run [flags] <image> [command...]

--name

string

Named volume ID. The volume is stored at DataRoot/volumes/<name>-data and survives container restarts.

--data

string

default:"/var/lib/minibox-data"

Container path where the named volume is mounted.

--shm-size

integer

default:"256"

Size of /dev/shm in megabytes. Postgres needs ≥128; MongoDB benefits from ≥256.

-p

string

Port mapping in host:container format. Repeat for multiple ports.

-e

string

Environment variable in KEY=VALUE format. Repeat for multiple variables.

--cmd

string

Shell command string. Executed as /bin/sh -c <cmd> when no positional command arguments are given.

-d

boolean

default:"true"

Always detached (accepted for symmetry with run; db run is always detached).

What `db run` configures differently

Setting	Value	Purpose
`db_mode`	`true`	Skips capability drop so DB entrypoints can `chown` data directories on first boot
`/dev/shm`	`--shm-size` MB	Postgres `shared_buffers`, MongoDB WiredTiger cache
`/dev/pts`	devpts mount	Required by `initdb` and DB shell tools
`/tmp`	tmpfs (mode 1777)	Used broadly by all DB engines
`/dev/ptmx`, `/dev/console`	created	Full POSIX device coverage
`io_weight`	`800`	High disk scheduling priority
`oom_score_adj`	`-900`	Last process to be OOM-killed

Postgres
MongoDB
Redis

minibox build -t minibox-postgres ./db-test/postgres
minibox db run \
  --name pg-data --data /var/lib/postgresql/data \
  --shm-size 256 -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_USER=app \
  -e POSTGRES_DB=mydb \
  minibox-postgres

# Connect
psql -h 127.0.0.1 -p 5432 -U app -d mydb

minibox build -t minibox-mongo ./db-test/mongo
minibox db run \
  --name mongo-data --data /data/db \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD=secret \
  minibox-mongo

# Connect
mongosh mongodb://root:secret@127.0.0.1:27017

minibox build -t minibox-redis ./db-test/redis
minibox db run \
  --name redis-data --data /data \
  --shm-size 64 -p 6379:6379 \
  minibox-redis

# Connect
redis-cli -h 127.0.0.1 -p 6379 ping

Database containers are experimental. Some images (e.g. Postgres) may exit early on kernels that restrict certain /dev operations. Ready-to-run helper scripts are provided under db-test/postgres/run.sh, db-test/mongo/run.sh, and db-test/redis/run.sh.

CLI Reference

API Reference

Architecture

minibox Build, Run, and Container Lifecycle Commands

ping

build

Health check support

run

ps

logs

exec

stop

kill

rm

stats

db run

What `db run` configures differently

Build docs developers (and LLMs) love

CLI Reference

API Reference

Architecture

Documentation Index

​ping

​build

​Health check support

​run

​ps

​logs

​exec

​stop

​kill

​rm

​stats

​db run

​What db run configures differently

Build docs developers (and LLMs) love

ping

build

Health check support

run

ps

logs

exec

stop

kill

rm

stats

db run

What `db run` configures differently