MiniBox File Directives: Complete Format Reference

A MiniBox file is the blueprint that tells minibox how to assemble an OCI-compliant container image. It combines a small set of top-level directives with indented block instructions to express a fully parallel, DAG-based build graph — keeping images lean while maximising build speed.

The file must be named MiniBox (formerly Boxfile). Place it at the root of your build context and run minibox build -t <name> . to start a build.

File Structure

Every MiniBox file follows the same three-part skeleton:

BASE <image>          # 1. Declare the root filesystem

BLOCK <name>          # 2. One or more named build stages
    <instructions…>

START <command>       # 3. Default container entrypoint

Top-level keywords (BASE, BLOCK, START, HEALTHCHECK) must have no leading whitespace. Instructions inside a block must be indented by at least 4 spaces or one tab.

Top-Level Directives

BASE

BASE <image>

(Required.) Declares the root filesystem that every block builds on top of. Four resolver types are supported — see Base Images for full details.

Syntax	Resolver
`BASE alpine:latest`	Docker Hub OCI pull
`BASE ghcr.io/user/repo:tag`	Custom OCI registry pull
`BASE scratch`	Empty filesystem (static binaries)
`BASE my-custom-base:latest`	Local previously-built image
`BASE ./rootfs.tar.gz`	Local tar or tar.gz archive

# Docker Hub shorthand
BASE node:18-slim

# Custom registry
BASE ghcr.io/myorg/mybase:1.0

# Empty filesystem for a Go static binary
BASE scratch

BLOCK

BLOCK <name>

Declares a named, independently cacheable build stage. Blocks form the nodes of the DAG — the builder works out which blocks can run in parallel based on their NEED / BNEED edges.

BLOCK builder
    run apk add --no-cache git
    workdir /src
    copy . .

BLOCK runtime
    BNEED builder
    copy FROM=builder /src/bin/app /app

Block names are arbitrary identifiers. Choose names that reflect their role — runtime, source, deps, config — so the build log is self-documenting.

START

START <command> [args…]

Sets the default command (entrypoint) that runs when a container is launched from this image. Only one START directive is allowed per file and it must appear at the top level.

START node index.js
START python main.py
START /server

HEALTHCHECK

HEALTHCHECK [--interval=<seconds>] <command> [args…]

Attaches a health-check probe to the image. The daemon runs the command periodically inside the container and updates the container’s Health field (starting → healthy / unhealthy).

Flag	Default	Description
`--interval=N`	`30`	Seconds between probe invocations

# Default 30-second interval
HEALTHCHECK curl -f http://localhost:3000/health

# Custom 10-second interval
HEALTHCHECK --interval=10 wget -qO- http://localhost:8080/ping

Healthcheck metadata is stored as OCI config labels (mini.healthcheck.cmd and mini.healthcheck.interval) and is visible in minibox ps.

Block Instructions

All instructions below must appear inside a BLOCK — indented by at least 4 spaces or one tab.

NEED vs BNEED

These two dependency directives control both execution ordering and what lands in the final image.

NEED — Runtime Dependency

The target block must finish before this block starts. Its filesystem layers are included in the final exported image, stacked beneath this block’s layer.Use NEED when your block genuinely needs packages, shared libraries, or files from another block at runtime.

BNEED — Build-time Dependency

The target block must finish before this block starts. Its filesystem layers are NOT included in the final image unless files are explicitly copied with COPY FROM=.Use BNEED when you only need artifacts from a builder stage — the heavy compiler toolchain stays out of production.

BLOCK runtime
    pkg nodejs

BLOCK source
    workdir /app
    copy . /app

BLOCK deps
    NEED runtime      # runtime layers ARE included → node binary is available
    NEED source       # source layers ARE included → /app files are present
    auto-deps

BLOCK final
    BNEED deps        # deps ran → node_modules built, but deps layers excluded
    copy FROM=deps /app/node_modules /app/node_modules
    env NODE_ENV=production

RUN

run <shell command>

Executes a command inside a chroot of the current overlay filesystem during the build. MiniBox automatically mounts /proc, /sys, /dev, and /tmp (mode 1777) so tools like apt, npm, and pip work correctly.

BLOCK builder
    run apk add --no-cache git curl
    run git clone https://github.com/example/repo /src
    run CGO_ENABLED=0 go build -o /app/server .

COPY

copy <src> <dest>
copy FROM=<block> <src> <dest>

Copies files or directories into the current block’s layer. Two forms exist: Local copy — source is resolved relative to the build context directory:

copy ./package.json /app/package.json
copy ./src /app/src
copy . /app

Stage copy — source is resolved from another block’s final layer directory. This is the primary mechanism for multi-stage size optimisation:

copy FROM=builder /app/server /usr/local/bin/server
copy FROM=builder /build/node_modules /app/node_modules

When COPY FROM=<block> is used, <block> is automatically added to the current block’s BNeeds list — you don’t need a separate BNEED directive.

AUTO-DEPS

auto-deps

Detects the project’s package manifest in the current WORKDIR and runs the appropriate dependency installer inside the chroot. The detection order is:

Manifest file	Command run
`package.json`	`npm install`
`requirements.txt`	`pip install -r requirements.txt`
`go.mod`	`go mod download`
`Cargo.toml`	`cargo build`

AUTO-DEPS always runs after all explicit instructions in the block have been executed.

BLOCK deps
    NEED runtime
    NEED source
    auto-deps        # detects package.json → runs npm install

AUTO-DEPS inspects the current workdir inside the overlay. Make sure a COPY or NEED of your source block has placed the manifest file before auto-deps is declared.

WORKDIR

workdir <path>

Sets the working directory for subsequent RUN commands in this block and configures the container’s default working directory. The path is created if it does not exist.

BLOCK builder
    workdir /build
    copy ./package.json /build/package.json
    run npm install

ENV

env KEY=VALUE
env KEY VALUE

Sets an environment variable in both the build environment (available to subsequent RUN commands) and the final image config (available at runtime).

env NODE_ENV=production
env PORT=3000
env DATABASE_URL=postgres://db:5432/app

PKG

pkg <name>
pkg <name>@<version>

Shorthand for installing Alpine packages. Expands to apk add --no-cache <package> under the hood. When a version is specified with @, it expands to apk add --no-cache <package>=<version>* to allow patch-level updates.

BLOCK runtime
    pkg nodejs
    pkg npm
    pkg git@2.40.1

PKG is specialised for Alpine Linux (apk). For Debian/Ubuntu base images, use RUN apt-get install -y <package> directly.

PORT

port <number>

Metadata directive that declares the port the container listens on. This information is stored in the image config and surfaced in minibox ps.

port 3000
port 8080

USER

user <username>

Sets the user that subsequent RUN commands and the final container process will run as. The user must already exist in the image’s /etc/passwd.

BLOCK runtime
    run adduser -D appuser
    user appuser

VOLUME

volume <path>

Declares a mount point path as a volume. This metadata is stored in the image config and signals that the path should be treated as externally mountable storage.

BLOCK runtime
    volume /data
    volume /var/log/app

Multi-Stage Size Optimisation

The BNEED + COPY FROM= pattern is the canonical way to build lean images. The builder stage compiles or installs everything; the runtime stage cherry-picks only the necessary artifacts.

Create a builder block

Install dev tools, compilers, or heavy dev dependencies and produce artifacts.

Create a runtime block with BNEED

BNEED builder tells MiniBox to wait for the builder to finish but exclude its layers from the final image.

Copy only what you need

Use COPY FROM=builder to bring compiled binaries or pre-built modules into the runtime block.

MiniBox prunes automatically

When exporting the OCI image, MiniBox only includes layers reachable via NEED edges from the last block — builder layers are automatically omitted.

Complete Examples

Node.js — Four-Block Runtime/Source/Deps/Config Pattern

This is the recommended structure for Node.js applications. The four blocks stay maximally cache-stable: installing system packages, copying source, running npm install, and setting config are all independent concerns.

BASE alpine

BLOCK runtime
    pkg nodejs
    pkg npm

BLOCK source
    workdir /app
    copy . /app

BLOCK deps
    NEED runtime
    NEED source
    auto-deps

BLOCK config
    NEED deps
    env PORT=3000
    env NODE_ENV=production
    port 3000

START node index.js

Why this works well:

runtime and source have no dependencies → they run in parallel in Wave 1.
deps needs both → Wave 2, runs npm install with the full overlay in place.
config just sets metadata → Wave 3, instant.
Changing only source files invalidates source and deps but not runtime (packages don’t reinstall).

Node.js — Lean Build with BNEED

Use this pattern when you want production-only artifacts without dev dependencies in the final image.

BASE node:18-slim

BLOCK builder
    run mkdir -p /build
    workdir /build
    copy ./package.json /build/package.json
    auto-deps
    copy ./src /build/src
    copy ./index.js /build/index.js

BLOCK runtime
    BNEED builder
    run mkdir -p /app
    copy FROM=builder /build/src /app/src
    copy FROM=builder /build/node_modules /app/node_modules
    copy FROM=builder /build/index.js /app/index.js
    copy ./package.json /app/package.json
    workdir /app
    env PORT=3000
    env NODE_ENV=production
    port 3001

START node index.js

Go — Static Binary from Scratch

BASE scratch starts with a completely empty filesystem. Combined with a statically linked Go binary this produces the smallest possible image.

BASE golang:1.21-alpine

BLOCK builder
    run apk add --no-cache git
    workdir /src
    copy . .
    run CGO_ENABLED=0 go build -o /app/server .

BLOCK runtime
    BNEED builder
    copy FROM=builder /app/server /server
    env PORT=8080

START /server

BASE can only be set at the top level of the file, not inside a BLOCK. All blocks share the same base filesystem declared at the top. To start with an empty filesystem, set BASE scratch at the top of the file.

BASE scratch images contain no shell, no libc, and no utilities. Your binary must be fully statically linked (CGO_ENABLED=0 for Go). Healthchecks that rely on curl or wget will not work in scratch images.

Legacy Format Aliases

For backward compatibility with older Boxfile syntax, the following aliases are recognised in flat files (no BLOCK or BASE keyword). The modern DAG format is strongly preferred for all new projects.

View legacy alias table

Legacy directive	Modern equivalent
`BOX` / `FROM` / `START-WITH`	`BASE`
`ADD-PACKAGE <pkg>`	`PKG <pkg>` (→ `apk add --no-cache`)
`INSTALL-DEPS`	`auto-deps` (or `RUN npm install`)
`CLONE-REPO <url>`	`RUN git clone <url>`
`RUN-COMMAND <cmd>`	`RUN <cmd>`
`GOTO-FOLDER <path>`	`WORKDIR <path>`
`SET-ENVIRONMENT KEY VALUE`	`ENV KEY=VALUE`
`IMPORT-FILE <src> <dest>`	`COPY <src> <dest>`
`GRAB-ALL` / `SYNC-PACK`	`COPY . /app`
`LAUNCH <cmd>`	`START <cmd>`

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

MiniBox File Directives: Complete Format Reference

File Structure

Top-Level Directives

BASE

BLOCK

START

HEALTHCHECK

Block Instructions

NEED vs BNEED

NEED — Runtime Dependency

BNEED — Build-time Dependency

RUN

COPY

AUTO-DEPS

WORKDIR

ENV

PKG

PORT

USER

VOLUME

Multi-Stage Size Optimisation

Complete Examples

Node.js — Four-Block Runtime/Source/Deps/Config Pattern

Node.js — Lean Build with BNEED

Go — Static Binary from Scratch

Legacy Format Aliases

Build docs developers (and LLMs) love

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Documentation Index

​File Structure

​Top-Level Directives

​BASE

​BLOCK

​START

​HEALTHCHECK

​Block Instructions

​NEED vs BNEED

NEED — Runtime Dependency

BNEED — Build-time Dependency

​RUN

​COPY

​AUTO-DEPS

​WORKDIR

​ENV

​PKG

​PORT

​USER

​VOLUME

​Multi-Stage Size Optimisation

​Complete Examples

​Node.js — Four-Block Runtime/Source/Deps/Config Pattern

​Node.js — Lean Build with BNEED

​Go — Static Binary from Scratch

​Legacy Format Aliases

Build docs developers (and LLMs) love

File Structure

Top-Level Directives

BASE

BLOCK

START

HEALTHCHECK

Block Instructions

NEED vs BNEED

RUN

COPY

AUTO-DEPS

WORKDIR

ENV

PKG

PORT

USER

VOLUME

Multi-Stage Size Optimisation

Complete Examples

Node.js — Four-Block Runtime/Source/Deps/Config Pattern

Node.js — Lean Build with BNEED

Go — Static Binary from Scratch

Legacy Format Aliases