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 applies layered hardening across three surfaces: the API, the container runtime, and the build pipeline. This page documents every control, where it is implemented, and its effective scope.

​
API Security

The miniboxd HTTP API exposes all build and runtime operations. The following controls protect the API surface.

​
Bearer Token Authentication

When MINIBOX_API_TOKEN is set, the requireAPIToken middleware in internal/api/auth.go enforces authentication on every request. Two header forms are accepted: 
Authorization: Bearer <token>
X-API-Token: <token>
If neither header is present or the token does not match, the server responds with: 
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="minibox"
When MINIBOX_API_TOKEN is not set, all requests are accepted without authentication. This is appropriate only for local-only, loopback-bound deployments.
If you bind the daemon to a non-loopback address (MINIBOX_HTTP_ADDR=0.0.0.0:8080), you must set MINIBOX_API_TOKEN. An unauthenticated daemon accessible on a network interface exposes full container build and run capabilities.

​
Method-Based Routing

Routes are registered with explicit HTTP methods (GET, POST) in internal/api/router.go. A request to a valid path with a wrong method returns 405 Method Not Allowed rather than falling through to the handler.

​
Request Body Limits

High-risk endpoints that accept user-controlled payloads (build context metadata, run options) have explicit request body size limits to prevent memory exhaustion from oversized payloads.

​
Security Response Headers

The API sets X-Content-Type-Options: nosniff on responses to prevent MIME-type sniffing by HTTP clients that may interpret responses in unexpected ways.

​
Runtime Hardening

Every container spawned by MiniBox is subject to the following isolation and restriction controls, applied in the child process before exec of the workload.

​
Namespace Isolation

MiniBox clones four Linux namespaces for each container:
NamespaceFlagEffect
PIDCLONE_NEWPIDContainer processes cannot see or signal host processes
UTSCLONE_NEWUTSContainer has its own hostname
MountCLONE_NEWNSContainer filesystem changes do not affect the host
NetworkCLONE_NEWNETContainer has an isolated network stack (its own eth0, routing table, and iptables state)

​
Seccomp Deny-List

A seccomp BPF filter (internal/runtime/seccomp_linux.go) is applied before the workload executes. The filter is deny-list based: a set of high-risk syscalls are blocked, and all others are permitted. PR_SET_NO_NEW_PRIVS is set via prctl(2) before the seccomp filter is loaded. This ensures the filter cannot be bypassed by a setuid or setgid binary inside the container. 
prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)   ← locks privilege escalation
seccomp(SECCOMP_SET_MODE_FILTER, ...)      ← deny-list filter applied
execve(workload)                           ← workload starts

​
Capability Drop

Capabilities are dropped in internal/runtime/drop_linux.go before exec. The workload starts with a minimal capability set, removing most host-administration capabilities.
db_mode exception — containers started with db_mode: true retain additional capabilities required by database engines (e.g. to chown data directories during initialization). This is an intentional pragmatic exception. Enable db_mode only for trusted database workloads, not for arbitrary or user-supplied images.

​
Resource Limits (rlimits)

Hard and soft resource limits are applied to the container process to bound runaway resource consumption. Limits are set on file descriptor count, process count, and core dump size.

​
cgroups v2

The daemon writes cgroup v2 knobs for the container:
KnobEffect
memory.maxCaps container memory usage
cpu.maxThrottles CPU share
cpuset.cpusPins to allowed CPUs
io.weightSets block I/O weight
cgroup.procsAssigns container PID to cgroup
For db_mode containers, oom_score_adj is set to -900 to make the OOM killer prefer other processes over the database.

​
Build Security

​
Build Context Path Restrictions

The MINIBOX_BUILD_PREFIXES environment variable defines which filesystem paths are allowed as build contexts. The check in internal/security/security.go (ResolveAllowedPath) resolves the submitted path to an absolute path, verifies it is a directory, and confirms it falls under one of the allowed prefixes. Default allowed prefixes: 
/home
/tmp
/var/lib/minibox
/root
/srv
/opt
/usr/local/src
A build request whose context resolves outside all prefixes is rejected with ErrBuildPathNotAllowed before any filesystem operation begins.

​
Path Traversal Prevention

The security package validates all container-scoped file paths with ContainerFile(). This function resolves the path to an absolute form and verifies it remains under the container’s directory using a strict prefix check. Any path that escapes the container directory returns ErrPathEscape. Container IDs are validated against a strict 8-character lowercase hex regular expression (^[a-f0-9]{8}$) before use in any filesystem operation.

​
Delete Safety

Before any deletion, SafeToDelete() in internal/security/security.go checks the target path against a list of protected system paths: 
var forbiddenPaths = []string{
    "/", "/home", "/root", "/usr", "/etc", "/var",
    "/boot", "/bin", "/sbin", "/dev", "/proc", "/sys", "/run",
}
It also refuses to delete the DataRoot directory itself or any path that escapes the data root.

​
Root Daemon Note

miniboxd requires root privileges to create network namespaces, configure iptables, and mount overlayfs. Run it with sudo -E miniboxd. User-namespace remapping (rootless execution) is not fully active in the current release. Test in a dedicated VM before deploying on shared infrastructure.
The daemon binds to 127.0.0.1:8080 by default, limiting its API to loopback access. For any environment where the loopback assumption is insufficient (multi-user systems, CI runners, exposed VMs), combine a non-default MINIBOX_HTTP_ADDR with a strong MINIBOX_API_TOKEN.

Build docs developers (and LLMs) love

Get started for freeTalk to us