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 supports basic container health checks defined directly in your MiniBox build file. A health check is a shell command that MiniBox runs periodically inside the container’s namespaces to determine whether the workload is responding correctly. The result is reflected in the HEALTH column shown by minibox ps.

​
Defining a health check

Add a HEALTHCHECK directive to your MiniBox file: 
BASE alpine

BLOCK app
    COPY . /app
    WORKDIR /app

START node index.js

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

​
Syntax

HEALTHCHECK [--interval=N] <command...>
​
--interval
integer
default:"30"
How often (in seconds) to run the health check command. Must be a positive integer. If omitted, the default is 30 seconds.
​
<command...>
string
required
The command to run inside the container. It is executed as /bin/sh -c <joined command>. An exit code of 0 means healthy; any non-zero exit code means unhealthy.

​
How health check metadata is stored

During minibox build, the MiniBox parser reads the HEALTHCHECK line and stores the command and interval as OCI image config labels:
OCI labelContent
mini.healthcheck.cmdCommand parts joined with the \x1f (unit separator) byte
mini.healthcheck.intervalInterval in seconds as a decimal string
These labels travel with the image through save/load and are read back by the runtime without any separate metadata file.

​
Health monitor goroutine

When minibox run starts a container whose image config contains mini.healthcheck.cmd, the runtime spawns a dedicated goroutine (startHealthMonitor) that:
1

Sets initial state to 'starting'

UpdateContainerHealth(containerID, "starting") is called immediately, before the first check fires. This prevents a race where ps shows none briefly after start.
2

Ticks at the configured interval

A time.Ticker fires every interval seconds (default 30). On each tick the goroutine verifies that the container is still running and has a valid PID — if not, the goroutine exits cleanly.
3

Runs the check via nsenter

The check command is executed on the host using nsenter:
nsenter -t <pid> -m -u -n -i -p -- /bin/sh -c <healthcheck cmd>
This enters all five namespaces (mount, UTS, network, IPC, PID) of the container process, so the command runs with the container’s view of the filesystem, hostname, network, and process tree.
4

Updates health state

  • Exit code 0 → UpdateContainerHealth(containerID, "healthy")
  • Non-zero exit → UpdateContainerHealth(containerID, "unhealthy")
Health state is persisted to DataRoot/state.json so it survives daemon restarts.

​
Health states

StateMeaningWhen set
startingContainer is running but no check has completed yetImmediately on container start, when a healthcheck is defined
healthyMost recent check exited with code 0After each passing nsenter run
unhealthyMost recent check exited non-zeroAfter each failing nsenter run
noneNo healthcheck defined in the image, or container has exitedNo mini.healthcheck.cmd label; or on container exit
When a container exits (for any reason), its health is unconditionally reset to none by MarkContainerExited().

​
Viewing health status with minibox ps

The HEALTH column appears in all ps output: 
minibox ps

ID         IMAGE    STATUS   HEALTH     EXIT  PORTS
a1b2c3d4   myapp    running  healthy    -     9000->80
b5e6f7a8   worker   running  starting   -
c9d0e1f2   oldapp   exited   none       0
Use minibox ps -a to include stopped containers.

​
Examples

BASE alpine

BLOCK deps
    pkg curl

BLOCK app
    WORKDIR /app
    COPY . /app

START ./myserver

HEALTHCHECK --interval=15 curl -sf http://127.0.0.1:8080/healthz

​
Limitations

MiniBox’s health check implementation provides basic liveness signalling. It is not full Docker HEALTHCHECK parity.
The following features from the Docker/OCI HEALTHCHECK spec are not yet implemented:
  • --start-period — There is no initial grace period during which failures are ignored. All checks after the first tick count toward the health state.
  • --retries — There is no retry counter. A single failed check immediately sets the state to unhealthy; a single passing check immediately sets it to healthy.
  • --timeout — Individual check executions do not have a per-run timeout. A hanging check command will block the monitor goroutine for that tick.
  • Shell form vs exec form — MiniBox always runs the health check as /bin/sh -c <cmd>. The exec form (JSON array syntax) is not supported.
Because nsenter is invoked from the host daemon process, the host must have nsenter installed (part of util-linux). If nsenter is not found at daemon startup, health checks will silently fail to run and the state will remain starting indefinitely.

Build docs developers (and LLMs) love

Get started for freeTalk to us