MiniBox Storage Layout Under DataRoot

All persistent data managed by miniboxd lives under a single directory called DataRoot. By default this is /var/lib/minibox, but you can override it with the MINIBOX_DATA_ROOT environment variable before starting the daemon.

export MINIBOX_DATA_ROOT="$HOME/.minibox-data"
sudo -E miniboxd

Annotated Directory Tree

DataRoot/                        # e.g. /var/lib/minibox
├── index.json                   # OCI image index: named image → manifest digest
├── state.json                   # Runtime state: ContainerInfo map for all containers
│
├── blobs/
│   └── sha256/
│       ├── <digest>             # OCI manifest JSON blob
│       ├── <digest>             # OCI config JSON blob
│       └── <digest>             # Layer blob (gzip-compressed tar)
│
├── layers/                      # DAG build cache (content-addressed block outputs)
│   └── <hash>/                  # One directory per cached block
│       └── <files...>           # Upper layer contents from overlay build
│
├── base_layers/                 # Pulled base image rootfs cache
│   └── <image_tag>/             # e.g. alpine-3.18/
│       └── <rootfs files>
│
├── containers/
│   └── <id>/                    # One directory per container (8-char hex ID)
│       ├── config.json          # Serialised RunRequest (image, cmd, ports, env, etc.)
│       ├── upper/               # OverlayFS upper layer (container writes)
│       ├── work/                # OverlayFS work directory (kernel internal)
│       ├── rootfs/              # Merged overlay mount point (container root)
│       └── container.log        # stdout/stderr of the container process
│
├── volumes/
│   └── <name>/                  # Named volume data (via named_volumes in RunRequest)
│
├── lazy/                        # Lazy layer fetch working area
├── cache/                       # General build/fetch cache
├── extracted/                   # Fully extracted layer trees
└── tmp/                         # Temporary files (cleaned by system prune)

File Reference

`index.json`

The OCI Image Index. Maps named images to their manifest blobs via content-addressed digests.

{
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:abcd1234...",
      "size": 512,
      "annotations": {
        "org.opencontainers.image.ref.name": "myapp"
      }
    }
  ]
}

Field	Type	Description
`schemaVersion`	integer	Always `2` (OCI index schema version)
`manifests[].mediaType`	string	MIME type of the referenced manifest blob
`manifests[].digest`	string	`sha256:<hex>` content address of the manifest blob
`manifests[].size`	integer	Size of the manifest blob in bytes
`manifests[].annotations["org.opencontainers.image.ref.name"]`	string	Human-readable image name used by `minibox run`, `ps`, etc.

`blobs/sha256/<digest>`

Content-addressed blob files. Three types of blob are stored here:

Manifest blob
Config blob
Layer blob

JSON file describing the image: points to a config blob and a list of layer blobs.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:config-digest",
    "size": 1024
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:layer1-digest",
      "size": 5242880
    }
  ]
}

JSON file with image runtime configuration and layer history.

{
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "Cmd": ["node", "index.js"],
    "Env": ["PORT=3000"],
    "WorkingDir": "/app",
    "Labels": {
      "mini.healthcheck.cmd": "wget -qO- http://127.0.0.1:3000/health",
      "mini.healthcheck.interval": "30"
    }
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": ["sha256:uncompressed-layer-digest"]
  }
}

Key config sub-fields:

Field	Description
`Cmd`	Default command (`START` directive in MiniBox file)
`Entrypoint`	Image entrypoint (may be set by base image)
`Env`	Environment variables (`ENV` directives)
`WorkingDir`	Default working directory (`WORKDIR` directive)
`Labels`	Metadata including healthcheck parameters
`ExposedPorts`	Declared ports (informational only)

A gzip-compressed tar archive of the filesystem changes produced by one DAG block. Layers are stacked in overlay order to form the container rootfs.

blobs/sha256/<sha256-of-compressed-tar>  # gzip-compressed tar
layers/<block-hash>/                      # uncompressed upper dir (build cache)

`layers/<hash>/`

The DAG build cache. Each directory corresponds to one cached block output, identified by a content-addressed hash that includes:

Parent block hash and dependency names
Inherited working directory
Full instruction stream (RUN, COPY, WORKDIR, ENV)
Hash of COPY source file trees (so changing source files invalidates the cache)
Whether AUTO-DEPS is enabled

If DataRoot/layers/<hash> exists when a block is about to run, the builder reports CACHED and skips execution. This directory is not affected by minibox rmi — only minibox system prune --build-cache removes it.

`base_layers/<image_tag>/`

Cached base image rootfs extracted from Docker Hub (or another OCI registry). Used as the bottom-most overlay layer for all containers built from that base. Pulled once and reused across builds.

`containers/<id>/`

One directory per container, named by the 8-character hex container ID.

File/Directory	Description
`config.json`	Serialized `RunRequest`: image, command, ports, env, memory, CPU, volumes, etc. Used by `containers/start` to restart a stopped container.
`upper/`	OverlayFS upper layer. All filesystem changes made by the running container land here.
`work/`	OverlayFS work directory required by the kernel. Not user-accessible.
`rootfs/`	The merged overlay mount point. This is the container’s root filesystem during execution.
`container.log`	stdout and stderr of the container process. Served by `GET /containers/logs`.

`volumes/<name>/`

Named volumes created via the named_volumes field in the RunRequest (or via data in minibox-compose.yaml). The daemon creates and owns these directories under DataRoot/volumes/<name> and bind-mounts them into the container at the specified path. They persist across container restarts and compose down / up cycles.

`state.json`

Persisted map of all container ContainerInfo records. Updated on every state transition (create, start, stop, exit, health change, remove). Read on daemon startup to restore knowledge of previously running containers.

`ContainerInfo` fields

string

8-character hex container ID generated at creation time.

image

string

Name of the image the container was started from.

command

string[]

The full command running inside the container (after Entrypoint + CMD resolution).

pid

integer

Host PID of the container’s parent process (the one that spawned the child namespaces). Used for signal delivery and process existence checks.

status

string

Current lifecycle status: running, exited, or created.

health

string

Health check status: starting, healthy, unhealthy, or none. Set to none when the container exits.

created_at

string

RFC3339 timestamp when the container was first registered.

exit_code

integer

Exit code recorded when the container exits. 137 indicates SIGKILL.

ports

object

Map of host port strings to container port strings (e.g. {"8080": "80"}). Reflects the iptables DNAT rules programmed at container start.

name

string

Optional human-readable name. Used for service discovery in compose projects.

project

string

Optional compose project name. Used to scope compose operations to a set of containers.

string

Container IP address on the minibox0 bridge network (e.g. 172.19.0.2). Used for service-name resolution in compose /etc/hosts injection.

Example state.json:

{
  "a1b2c3d4": {
    "id": "a1b2c3d4",
    "image": "myapp",
    "command": ["node", "index.js"],
    "pid": 12345,
    "status": "running",
    "health": "healthy",
    "created_at": "2024-01-15T10:30:00Z",
    "exit_code": 0,
    "ports": {"8080": "80"},
    "name": "web",
    "project": "my-app",
    "ip": "172.19.0.2"
  }
}

On daemon startup, all containers listed as running in state.json are live-checked by sending signal 0 to their PID. Containers whose process no longer exists are automatically transitioned to exited status.

Resetting the Data Root

To completely wipe all minibox data and start fresh:

# Use the provided cleanup script (handles root-owned overlay files)
sudo ./scripts/clean-data.sh

# Or point to a fresh directory
export MINIBOX_DATA_ROOT="$HOME/.minibox-data-new"
sudo -E miniboxd

The data root may contain root-owned files created by overlay mounts. Do not use rm -rf directly — use clean-data.sh or an appropriate sudo command to avoid permission errors.

CLI Reference

API Reference

Architecture

MiniBox Storage Layout Under DataRoot

Annotated Directory Tree

File Reference

`index.json`

`blobs/sha256/<digest>`

`layers/<hash>/`

`base_layers/<image_tag>/`

`containers/<id>/`

`volumes/<name>/`

`state.json`

`ContainerInfo` fields

Resetting the Data Root

Build docs developers (and LLMs) love

CLI Reference

API Reference

Architecture

Documentation Index

​Annotated Directory Tree

​File Reference

​index.json

​blobs/sha256/<digest>

​layers/<hash>/

​base_layers/<image_tag>/

​containers/<id>/

​volumes/<name>/

​state.json

​ContainerInfo fields

​Resetting the Data Root

Build docs developers (and LLMs) love

Annotated Directory Tree

File Reference

`index.json`

`blobs/sha256/<digest>`

`layers/<hash>/`

`base_layers/<image_tag>/`

`containers/<id>/`

`volumes/<name>/`

`state.json`

`ContainerInfo` fields

Resetting the Data Root