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 a small Linux container engine written in Go. It builds images from MiniBox files, stores them in an OCI-like blob store, and runs containers using Linux namespaces, overlayfs, and a root daemon — all from a single CLI. This project is beta quality: fully usable for testing and learning, with known limitations documented below.

​
Two-Binary Architecture

MiniBox ships as two binaries that work together over a local HTTP API.

minibox

The CLI client. Sends commands to the daemon over HTTP (127.0.0.1:8080 by default). Handles build, run, ps, logs, images, compose, and all other user-facing operations. Does not require root.

miniboxd

The daemon. Runs the HTTP API, container runtime, image builder, networking stack, and state manager. Must run as root for overlayfs mounts, network bridge setup, and iptables rules.
The CLI is a thin HTTP client. Every command — build, run, ps, stop, rm, images — translates to an API call to the daemon. The daemon does all the heavy lifting: parsing MiniBox files, executing build blocks, managing overlayfs layers, spawning containers in isolated namespaces, and configuring iptables port mappings.

​
What Is Implemented

MiniBox covers the full container lifecycle from image build to running container.

​
Image Builds

MiniBox files describe images as a directed acyclic graph (DAG) of named BLOCK units. Each block is an independently cacheable layer. The builder executes blocks in parallel waves: all blocks whose NEED dependencies are satisfied run concurrently in the same wave. Key directives:
DirectiveDescription
BASE <name>Base rootfs (Alpine is the supported base)
BLOCK <name>Named, cacheable build unit
NEED <block>Dependency edge — this block sees dependent layers in its overlay stack
BNEED <block>Build-only dependency — layers from the referenced block are available during build but not at runtime
RUN <cmd>Shell command executed inside the block layer
COPY <src> <dst>Copy files from build context into the layer
WORKDIR <path>Set working directory for subsequent instructions
ENV KEY=VALUESet environment variable in the image
PKG <name>[@ver]Expands to apk add --no-cache (Alpine)
AUTO-DEPSDetects manifests (e.g. package.json) and runs installers
PORT <num>Document the port the container listens on (metadata only; does not create iptables rules)
USER <name>Set the user for subsequent instructions
VOLUME <path>Declare a container mount point
HEALTHCHECK [--interval=N] <cmd>Define a health check command; default interval is 30 seconds
START <cmd>Default command for containers started from this image

​
OCI-Like Storage

Images are stored in a content-addressed blob store under DataRoot/blobs/sha256. An index.json file maps image names to their manifests. Build cache layers live separately under DataRoot/layers/<hash>, keyed by a hash of the instruction stream plus COPY content hashes.

​
Container Runtime

Every container runs in a fully isolated environment:
  • Namespaces: PID, UTS, MNT, and NET — each container gets its own process tree, hostname, mount table, and network stack
  • Overlayfs rootfs: Container filesystem is an overlay on top of image layers; writes are isolated to a per-container upper directory
  • Tiny init/reaper: PID 1 in each container is a minimal init process that reaps zombie processes
  • Seccomp: Deny-list syscall filter applied on container start
  • Capability drop: Capabilities are dropped at start; DB-mode containers retain a subset needed for database initialization
  • Cgroups v2: Memory limit, CPU quota/set, IO weight, OOM score adjustment, and sysctls are all configurable per container
  • rlimits: Resource limits applied via setrlimit

​
Networking

  • A minibox0 Linux bridge is created on first container run (lazy setup)
  • Each container gets a veth pair: one end in the container network namespace, one end attached to the bridge
  • iptables NAT and DNAT rules implement port mappings (-p host:container)
  • Containers can reach the internet through the bridge via NAT masquerade

​
Compose Orchestration

A minibox-compose.yaml file describes multi-container projects. Services are started in dependency order using a DAG resolver (depends_on). Service discovery is implemented via dynamic /etc/hosts management — each container gets entries for the other services in the project.

​
State and Observability

  • state.json persists container state across daemon restarts
  • minibox ps shows status, exit code, ports, and health for every container
  • minibox stats streams live cgroups metrics (memory, CPU, IO) for a running container
  • minibox logs fetches stdout/stderr from containers/<id>/container.log
  • minibox images shows image size and name

​
Image Portability

minibox save <image> <out.tar> exports an image to a tar archive of the internal OCI-like store. minibox load <in.tar> imports it. Note: this format is not compatible with Docker’s docker save format.

​
End-to-End Architecture

The following diagram shows how a user CLI command flows through the system all the way to a running container, network rule, and persistent state:

​
Key Features at a Glance

  • DAG-based parallel builds — blocks in the same dependency wave execute concurrently, making builds fast even for complex images
  • Content-addressed build cache — each block’s cache key includes its instruction stream and COPY source hashes; only changed blocks rebuild
  • Full namespace isolation — PID, UTS, MNT, NET namespaces per container; no shared process tree or mount table with the host
  • Cgroups v2 resource limits — memory, CPU, and IO limits enforced by the kernel; containers cannot exceed their allocation
  • iptables port mappings — host-to-container port forwarding via NAT DNAT rules, supporting multiple -p flags per container
  • Service discovery in Compose — dynamic /etc/hosts entries let services address each other by name without a DNS server
  • Live stats — minibox stats streams real cgroups data every second
  • System prune — minibox system prune cleans orphaned blobs, lazy mounts, and temporary data; --build-cache also clears the DAG layer cache

​
Known Limitations (Beta)

MiniBox is beta software. It is suitable for testing and learning, but has known gaps compared to production container runtimes.
  • Root daemon required — networking setup, overlayfs mounts, and iptables rules all require root
  • DB containers are experimental — some database images (e.g. Postgres) may exit early on kernels that restrict /dev access; this will be improved
  • Not a full OCI runtime — no OCI spec parity for hooks, lifecycle, or full userns mapping
  • Security model is learning-grade — seccomp is a deny-list, capability dropping is pragmatic; not suitable for untrusted multi-tenant workloads
  • save/load format — uses an internal archive format, not compatible with docker save or other OCI tools
  • Alpine only — BASE currently supports Alpine as the base rootfs; other distributions are not yet supported

​
Safety Note

MiniBox runs a root daemon that performs host-level operations: overlayfs mounts, iptables rules, network bridge and veth setup. Always test in a VM before deploying to shared or production systems. Point MINIBOX_DATA_ROOT at a safe directory and never at a system path.
The recommended setup: 
export MINIBOX_DATA_ROOT="$HOME/.minibox-data"
This keeps all images, containers, blobs, and layers under your home directory and makes cleanup straightforward.

​
Get Started

Quickstart

Build and run your first container in under five minutes.

Installation

Install minibox and miniboxd and configure your environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us