MiniBox Architecture Deep Dive

MiniBox is a lightweight Linux container engine consisting of two binaries: minibox (CLI) and miniboxd (daemon). The CLI is a pure HTTP client; all container logic lives in the daemon. This page describes the full system — from parsing a MiniBox file to a running container process with networking, cgroups, and health checks.

Two-Binary Architecture

Binary	Entry point	Responsibility
`miniboxd`	`cmd/daemon/main.go`	HTTP API, builder, runtime, networking, state
`minibox`	`cmd/cli/main.go`	CLI commands → HTTP requests → formatted output

The CLI never directly touches container namespaces, overlay mounts, or iptables. Every operation is delegated to miniboxd over HTTP (http://127.0.0.1:8080 by default).

End-to-End Flowchart

Build Pipeline

1. Parse phase

internal/parser/parser.go reads a MiniBox file and produces a Cfile model containing:

BaseImage — the base rootfs to pull
Blocks — a list of named DAG build units
Cmd, Env, Workdir — image-level defaults
HealthcheckCmd, HealthcheckIntervalSec — for health monitoring
Instructions — legacy linear mode fallback

DAG directives:

Directive	Meaning
`BASE <image>`	Base rootfs (Alpine supported)
`BLOCK <name>`	Named build unit
`NEED <block>`	Dependency edge
`RUN ...`	Shell command in block context
`COPY <src> <dst>`	Copy from context or another block (`COPY FROM=`)
`WORKDIR <path>`	Set working directory
`ENV KEY=VAL`	Environment variable
`PKG <name>`	Expands to `apk add --no-cache <name>`
`AUTO-DEPS`	Detects manifests and runs installers (npm, pip, go)
`START ...`	Image default command
`HEALTHCHECK [--interval=N] <cmd>`	Health check definition

2. Base image prep

internal/builder/fetch_oci.go pulls the base image from Docker Hub (or any Docker V2 registry):

Fetches the manifest from auth.docker.io
Resolves multi-arch manifest lists to linux/amd64
Downloads layer blobs
Caches extracted rootfs in DataRoot/base_layers/<image_tag>

3. DAG execution (wave-based parallelism)

builder.BuildImage() calls buildFromBlocks():

Compute wavefronts

Identify all blocks whose NEED dependencies are already complete. These form a wave and run concurrently.

Execute each block

For each block:

Create a temp overlay root (tmp/<hash>/{upper,work,root})
For RUN instructions: mount overlay and execute chroot /bin/sh -c ...
For COPY instructions: copy from the host context or from another block’s layer
For WORKDIR: create path and update effective working directory

Cache check

The cache key is derived from: parent hash + dependency names + workdir + instruction stream + COPY source content hash. If DataRoot/layers/<hash> exists, the block is CACHED.

Finalize layer

Move the overlay upper directory into DataRoot/layers/<hash>.

Advance

Mark the wave complete and compute the next wavefront.

Build-only blocks (BNEED) are executed but excluded from the final image layer stack unless files are explicitly copied from them.

4. OCI finalization

After all blocks complete:

Tar + gzip each layer → blobs/sha256/<digest>
Generate OCIConfig blob (cmd, env, workdir, healthcheck labels, layer diff IDs)
Generate OCIManifest blob (config + layer descriptors)
Upsert image reference into index.json with annotation org.opencontainers.image.ref.name = <imageName>

Build log format

[build] START image=myapp
[base] pulling alpine ...
[build] mode=dag blocks=4
[dag] wave=1 ready=runtime,layout
[block] START runtime
[block] CACHED source
[dag] wave=1 done elapsed=1.2s
[dag] wave=2 ready=deps
[block] START deps
[dag-summary] cached=1 built=3
[finalize] writing blobs ...
[build] DONE image=myapp

Runtime Execution Path

Parent launcher (`internal/runtime/process.go`)

RunCommand() / RunCommandStream():

Resolve image config and layer stack from OCI index
Prepare DataRoot/containers/<id>/ and mount overlay rootfs (MountRootfs)
Spawn child as /proc/self/exe child ... with clone flags: CLONE_NEWPID | CLONE_NEWUTS | CLONE_NEWNS | CLONE_NEWNET | CLONE_NEWIPC
Call SetupContainerNetwork(pid, id, ip, portMap)
Register container in state.json via RegisterContainer()
Start health monitor goroutine (if image has healthcheck labels)
Wait for child; record exit code; teardown network

Child runtime (`internal/runtime/container.go`)

RunContainer():

Validate args and container ID
Ensure mount namespace isolation (env guard + optional unshare fallback)
Apply cgroup writes: memory.max, cpu.max, cgroup.procs, io.weight
Set hostname
chroot into container rootfs
Mount /proc, minimal /dev
Apply security: capability drop, rlimits, PR_SET_NO_NEW_PRIVS, seccomp deny-list
Exec tiny init: /proc/self/exe init -- <cmd...>

Tiny init / PID 1 (`internal/runtime/init.go`)

RunInit():

Starts the target command
Forwards signals to the process group
Reaps zombie processes with wait4(-1, ...)
Exits with child status/signal semantics

This prevents zombie accumulation when the workload forks subprocesses, providing PID 1 semantics without a full init system.

Networking Architecture

Implemented in internal/network/network.go.

Host bridge setup (`SetupBridge`)

Creates minibox0 bridge and assigns 172.19.0.1/24
Enables IP forwarding sysctls
Adds iptables NAT masquerade rules

When MINIBOX_BRIDGE_ON_STARTUP=0, bridge creation is deferred to the first container run, making daemon startup near-instant.

Per-container networking (`SetupContainerNetwork`)

For each container:

Create veth pair: veth-<id> (host) and vetp-<id> (peer)
Attach host veth to minibox0 bridge
Move peer veth into the container’s network namespace (via PID)
Inside the container netns: bring up loopback, rename peer to eth0, assign IP, add default route via 172.19.0.1
Program iptables DNAT and FORWARD rules for each -p host:container mapping

Teardown

TeardownContainerNetwork() removes veth pairs and per-container iptables rules
TeardownBridge() removes minibox0 and the base NAT setup (called on daemon shutdown)

Security Controls

API layer

Method-scoped routes enforce correct HTTP verbs
Body size limits: 4 MB (run/exec), 64 MB (build)
Optional bearer token authentication middleware
Input validation via internal/security/security.go (image names, container IDs, path traversal)

Runtime layer

Control	Implementation
Namespace isolation	PID, UTS, mount, network, IPC via clone flags
Seccomp	Deny-list filter in `internal/runtime/seccomp_linux.go`
Capability drop	`internal/runtime/drop_linux.go` (skipped in `db_mode`)
No new privileges	`PR_SET_NO_NEW_PRIVS` set before seccomp
Path traversal	Container ID and path validation before any file operations

Build context restrictions

Build contexts are validated against MINIBOX_BUILD_PREFIXES using security.ResolveAllowedPath(). Requests with contexts outside the allowed prefixes are rejected at the handler level.

Health Checks

HEALTHCHECK [--interval=N] <cmd> is parsed from the MiniBox file
Stored as OCI config labels: mini.healthcheck.cmd, mini.healthcheck.interval
On container start, a monitor goroutine runs nsenter ... /bin/sh -c <cmd> periodically
Container Health field transitions: starting → healthy or unhealthy
minibox ps shows the current HEALTH column value

Health check support is basic. Retries, start-period thresholds, and full OCI HealthConfig semantics are not yet implemented.

Compose Orchestration

cmd/cli/main.go implements the compose orchestrator on top of the daemon API:

Service DAG

minibox-compose.yaml is parsed with gopkg.in/yaml.v3
A dependency graph is built from depends_on declarations
Topological sort determines startup order: services with no dependencies start first

Automated builds

Services with a build context trigger POST /containers/build before starting
The resulting image is tagged <project>-<service>

Service discovery

When a container starts as part of a project:

The daemon fetches all running containers in the same project
Builds a hosts-file mapping service names and container IDs → IP addresses
Writes the mapping to rootfs/etc/hosts before PID 1 executes

This allows web to connect to db:5432 without any DNS configuration.

File Map

Path	Responsibility
`cmd/daemon/main.go`	Daemon entry point
`cmd/cli/main.go`	CLI + compose orchestrator
`internal/api/router.go`	HTTP route registration, body limits, middleware chain
`internal/api/auth.go`	Bearer token middleware
`internal/api/handler/*.go`	Per-endpoint request handlers
`internal/builder/builder.go`	DAG build orchestration
`internal/builder/fetch_oci.go`	OCI image pulling from registries
`internal/parser/parser.go`	MiniBox file parser
`internal/runtime/process.go`	Parent container launcher
`internal/runtime/container.go`	Child namespace + chroot setup
`internal/runtime/init.go`	PID 1 tiny init / zombie reaper
`internal/runtime/state.go`	Container state persistence
`internal/runtime/seccomp_linux.go`	Seccomp deny-list filter
`internal/runtime/drop_linux.go`	Capability dropping
`internal/network/network.go`	Bridge, veth, iptables
`internal/storage/image_archive.go`	save / load tar operations
`internal/storage/prune.go`	Blob garbage collection
`internal/models/oci.go`	OCI data model types
`internal/security/security.go`	Input validation helpers
`internal/config/config.go`	Daemon configuration from env vars

CLI Reference

API Reference

Architecture

MiniBox Architecture Deep Dive

Two-Binary Architecture

End-to-End Flowchart

Build Pipeline

1. Parse phase

2. Base image prep

3. DAG execution (wave-based parallelism)

4. OCI finalization

Build log format

Runtime Execution Path

Parent launcher (`internal/runtime/process.go`)

Child runtime (`internal/runtime/container.go`)

Tiny init / PID 1 (`internal/runtime/init.go`)

Networking Architecture

Host bridge setup (`SetupBridge`)

Per-container networking (`SetupContainerNetwork`)

Teardown

Security Controls

API layer

Runtime layer

Build context restrictions

Health Checks

Compose Orchestration

Service DAG

Automated builds

Service discovery

File Map

Build docs developers (and LLMs) love

CLI Reference

API Reference

Architecture

Documentation Index

​Two-Binary Architecture

​End-to-End Flowchart

​Build Pipeline

​1. Parse phase

​2. Base image prep

​3. DAG execution (wave-based parallelism)

​4. OCI finalization

​Build log format

​Runtime Execution Path

​Parent launcher (internal/runtime/process.go)

​Child runtime (internal/runtime/container.go)

​Tiny init / PID 1 (internal/runtime/init.go)

​Networking Architecture

​Host bridge setup (SetupBridge)

​Per-container networking (SetupContainerNetwork)

​Teardown

​Security Controls

​API layer

​Runtime layer

​Build context restrictions

​Health Checks

​Compose Orchestration

​Service DAG

​Automated builds

​Service discovery

​File Map

Build docs developers (and LLMs) love

Two-Binary Architecture

End-to-End Flowchart

Build Pipeline

1. Parse phase

2. Base image prep

3. DAG execution (wave-based parallelism)

4. OCI finalization

Build log format

Runtime Execution Path

Parent launcher (`internal/runtime/process.go`)

Child runtime (`internal/runtime/container.go`)

Tiny init / PID 1 (`internal/runtime/init.go`)

Networking Architecture

Host bridge setup (`SetupBridge`)

Per-container networking (`SetupContainerNetwork`)

Teardown

Security Controls

API layer

Runtime layer

Build context restrictions

Health Checks

Compose Orchestration

Service DAG

Automated builds

Service discovery

File Map