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.

miniboxd exposes a plain HTTP API that the minibox CLI uses for all operations. Every CLI command is a thin wrapper over one of these endpoints. You can also call the API directly with curl or any HTTP client for scripting and integration.

​
Base URL

http://127.0.0.1:8080
The daemon binds to 127.0.0.1 (loopback) by default so the API is not reachable from other hosts. Override with MINIBOX_HTTP_ADDR: 
# Expose on all interfaces (use with caution)
export MINIBOX_HTTP_ADDR=":8080"

​
Authentication

Authentication is optional but strongly recommended. When MINIBOX_API_TOKEN is set on the daemon, every request must include the token. The daemon accepts it in either of two headers: 
curl http://127.0.0.1:8080/ping \
  -H "Authorization: Bearer <your-token>"
Requests with a missing or incorrect token receive: 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="minibox"

Unauthorized
When MINIBOX_API_TOKEN is not set on the daemon, all requests are accepted without authentication.

​
Request Body Limits

The daemon enforces per-endpoint request body size limits to prevent resource exhaustion:
EndpointBody limit
POST /containers/run4 MB
POST /containers/exec4 MB
POST /containers/build64 MB
All other endpointsNo enforced limit
Requests that exceed the limit are rejected with 413 Request Entity Too Large.

​
Security Headers

Every response from the daemon includes:
HeaderValue
X-Content-Type-Optionsnosniff
This is applied by the secureHeaders middleware that wraps all routes.

​
All Routes

The following table lists all 17 routes registered in internal/api/router.go:
MethodPathDescription
GET/pingDaemon health check
POST/containers/runCreate and run a container
POST/containers/buildBuild an image from a MiniBox file
POST/containers/execExecute a command in a running container
GET/containersList all containers
GET/containers/logsFetch container logs
GET/containers/statsGet live container resource stats
POST/containers/stopStop a container (SIGTERM then SIGKILL)
POST/containers/startStart a stopped container
POST/containers/killForce-kill a container (SIGKILL)
POST/containers/removeRemove a container record and data
GET/imagesList local images
POST/images/pullPull an OCI image from a registry
POST/images/saveExport an image to a tar archive
POST/images/loadImport an image from a tar archive
POST/images/removeRemove an image from the index
POST/system/pruneGarbage-collect unused blobs and layers

​
Response Format

Most endpoints return plain text for simple confirmations (e.g. Container a1b2c3d4 stopped\n) and JSON for structured data (e.g. GET /containers, GET /images). Endpoints that stream output (build, run foreground) use Transfer-Encoding: chunked with progressive newline-delimited text. Error responses use standard HTTP status codes with a plain-text body:
StatusMeaning
200 OKSuccess
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid API token
404 Not FoundContainer or image not found
500 Internal Server ErrorDaemon-side failure

​
API Reference Pages

Container Endpoints

/ping, /containers/run, /build, /exec, /logs, /stats, /stop, /start, /kill, /remove

Image Endpoints

/images, /images/pull, /save, /load, /remove, /system/prune

Build docs developers (and LLMs) love

Get started for freeTalk to us