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.

These endpoints cover the full container lifecycle managed by miniboxd. All examples use curl with an Authorization header — omit the header if MINIBOX_API_TOKEN is not set on the daemon.

​
GET /ping

Check that the daemon is alive and responding. 
GET /ping
Response: 200 OK with body Daemon is running 
curl http://127.0.0.1:8080/ping \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /containers/build

Build an OCI image from a MiniBox file content and a context directory path. The request body is limited to 64 MB. 
POST /containers/build
Content-Type: application/json

​
Request Body

​
image
string
required
The name (tag) to assign to the built image. Must be a valid image name (alphanumeric, hyphens, underscores).
​
minibox
string
required
Full content of the MiniBox file as a string. The daemon parses and executes this content.
​
context
string
required
Absolute path on the daemon host to the build context directory. Must fall under a path allowed by MINIBOX_BUILD_PREFIXES.

​
Response

200 OK — streamed plain text build log using Transfer-Encoding: chunked. Each line is prefixed with the build stage (e.g. [build], [dag], [block], [finalize]). 
MINIBOX_CONTENT=$(cat ./MiniBox)

curl -X POST http://127.0.0.1:8080/containers/build \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"image\": \"myapp\",
    \"minibox\": $(echo "$MINIBOX_CONTENT" | jq -Rs .),
    \"context\": \"/home/user/my-project\"
  }"

​
POST /containers/run

Create and run a new container from a locally built image. The request body is limited to 4 MB. 
POST /containers/run
Content-Type: application/json

​
Request Body

​
image
string
required
Name of the image to run. Must exist in the local index.json.
​
command
string[]
Command and arguments to execute. If omitted, the image’s default Entrypoint + CMD is used. If the image has an Entrypoint, the provided command is appended to it.
​
detached
boolean
default:"false"
Run in detached mode. Returns the container ID immediately without streaming output.
​
memory
integer
Memory limit in megabytes. Written to the cgroup memory.max.
​
cpu
integer
CPU quota in cgroup v2 cpu.max units (microseconds per 100ms period).
​
cpuset
string
CPU cores the container may use (e.g. "0,1"). Written to the cgroup cpuset.cpus.
​
io_weight
integer
I/O weight for the container’s cgroup. Valid range: 1–1000.
​
oom_score_adj
integer
OOM killer score adjustment for the container process. Valid range: -1000 to 1000.
​
sysctls
object
Kernel parameters to set inside the container’s network namespace, as a JSON object mapping sysctl key to value (e.g. {"net.core.somaxconn": "1024"}).
​
ports
object
Port mappings as a JSON object mapping host port strings to container port strings. Example: {"8080": "80"}.
​
env
string[]
Environment variables in KEY=VALUE format.
​
volumes
object
Bind mounts as a JSON object mapping host paths to container paths.
​
named_volumes
object
Named volumes as a JSON object mapping volume names to container paths. The daemon creates DataRoot/volumes/<name> on the host automatically.
​
interactive
boolean
default:"false"
Allocate a PTY and stream stdin. The daemon hijacks the HTTP connection for raw TCP interaction.
​
db_mode
boolean
default:"false"
Enable database mode: skips capability drop, mounts devpts and tmpfs, sets high IO weight, and sets OOM score adjustment to -900.
​
shm_size
integer
default:"256"
Size of /dev/shm in megabytes (used when db_mode is true or explicitly requested).
​
user
string
Username or UID to run the container process as (e.g. "nobody" or "1000").
​
name
string
Human-readable name for the container. Used for service discovery in compose projects.
​
project
string
Compose project name. Used to group containers for compose operations.

​
Response

200 OK — In detached mode, the response body is the 8-character hex container ID followed by a newline (plain text). In foreground mode, the response body is the streamed container output as plain text. 
# Detached
curl -X POST http://127.0.0.1:8080/containers/run \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "myapp",
    "detached": true,
    "ports": {"8080": "80"},
    "memory": 512
  }'

# Foreground with command override
curl -X POST http://127.0.0.1:8080/containers/run \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "alpine",
    "command": ["/bin/sh", "-c", "echo hello"]
  }'

​
POST /containers/exec

Run a command inside a running container by entering its namespaces. The request body is limited to 4 MB. 
POST /containers/exec
Content-Type: application/json

​
Request Body

​
id
string
required
The 8-character hex ID of a running container.
​
command
string[]
required
Command and arguments to execute inside the container.
​
interactive
boolean
default:"false"
Attach stdin/stdout/stderr for interactive use. The daemon hijacks the HTTP connection for raw TCP streaming.

​
Response

200 OK — command output as plain text (non-interactive), or raw TCP stream (interactive). 
curl -X POST http://127.0.0.1:8080/containers/exec \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a1b2c3d4",
    "command": ["ls", "-la", "/"]
  }'

​
GET /containers

List all containers known to the daemon. 
GET /containers

​
Response

​
body
object
JSON object mapping container IDs to ContainerInfo objects.
curl "http://127.0.0.1:8080/containers" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
GET /containers/logs

Fetch the stdout/stderr log for a container. 
GET /containers/logs?id=<containerID>&follow=<0|1>
​
id
string
required
The 8-character hex container ID.
​
follow
string
default:"0"
Set to 1 to tail the log file and stream new output as it arrives. The response is kept open until the client disconnects.

​
Response

200 OK — plain text log content served directly from DataRoot/containers/<id>/container.log. In follow mode (follow=1), uses Transfer-Encoding: chunked and streams continuously. 
# Fetch log snapshot
curl "http://127.0.0.1:8080/containers/logs?id=a1b2c3d4" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

# Tail log in real time
curl "http://127.0.0.1:8080/containers/logs?id=a1b2c3d4&follow=1" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
GET /containers/stats

Get live cgroup resource stats for a running container. 
GET /containers/stats?id=<containerID>
​
id
string
required
The 8-character hex container ID.

​
Response

200 OK — JSON object with memory, CPU, PID count, I/O, and network statistics read from cgroup v2 and host veth counters. 
curl "http://127.0.0.1:8080/containers/stats?id=a1b2c3d4" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /containers/stop

Stop a running container with SIGTERM, falling back to SIGKILL after a timeout. 
POST /containers/stop?id=<containerID>&t=<seconds>
​
id
string
required
The 8-character hex container ID.
​
t
integer
default:"10"
Timeout in seconds before SIGKILL is sent. Range: 0–600.

​
Response

200 OK — Container <id> stopped\n or Container <id> killed (timeout)\n 
curl -X POST "http://127.0.0.1:8080/containers/stop?id=a1b2c3d4&t=30" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /containers/start

Restart a stopped container using its saved configuration. 
POST /containers/start?id=<containerID>
​
id
string
required
The 8-character hex container ID of a stopped container.

​
Response

200 OK — container ID or status message. 
curl -X POST "http://127.0.0.1:8080/containers/start?id=a1b2c3d4" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /containers/kill

Force-kill a container immediately with SIGKILL. 
POST /containers/kill?id=<containerID>
​
id
string
required
The 8-character hex container ID.

​
Response

200 OK — Container <id> killed\n. Exit code is recorded as 137. 
curl -X POST "http://127.0.0.1:8080/containers/kill?id=a1b2c3d4" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"

​
POST /containers/remove

Remove a container record and delete its directory from disk. 
POST /containers/remove?id=<containerID>
​
id
string
required
The 8-character hex container ID.

​
Response

200 OK — Container <id> removed\n 
curl -X POST "http://127.0.0.1:8080/containers/remove?id=a1b2c3d4" \
  -H "Authorization: Bearer $MINIBOX_API_TOKEN"
This operation permanently deletes DataRoot/containers/<id>/ including logs. It cannot be undone.

Build docs developers (and LLMs) love

Get started for freeTalk to us