Running Containers with MiniBox: Namespaces and Cgroups

MiniBox runs containers as isolated Linux processes using PID, UTS, mount, and network namespaces combined with cgroups v2 resource controls. This page covers every stage of the container lifecycle — from launching your first container with minibox run all the way through inspecting it with stats and cleaning up with rm.

Prerequisites

The daemon must be running before you issue any container commands:

sudo -E miniboxd
minibox ping   # should print: Daemon is running

`minibox run` flags

-d

flag

Detached mode. The container starts in the background and its 8-hex-character ID is printed to stdout.

-m

integer

Memory limit in megabytes. Written to memory.max in the container’s cgroup v2 slice under /sys/fs/cgroup/minibox/<id>/.

-c

integer

CPU limit as a percentage of one core (1–100). MiniBox converts this to the cgroup v2 cpu.max format: <quota> 100000, where quota = value × 100000 / 100.

-p

string

Port mapping in host:container format (e.g. -p 8080:80). Repeat the flag for multiple mappings. MiniBox programs an iptables DNAT rule and a kernel-bypass TCP proxy listener for each pair.

Full usage:

minibox run [-d] [-m <memoryMB>] [-c <cpuPercent>] [-p <host:container>] <image> [command...]

If you omit command, MiniBox uses the image’s default CMD from its OCI metadata.

Container lifecycle

Build an image

minibox build -t myapp .

Run the container

# Foreground — output streams to your terminal
minibox run myapp

# Detached — prints the container ID and returns immediately
minibox run -d myapp

Inspect running containers

minibox ps        # running containers only
minibox ps -a     # include stopped / exited

ps shows ID, IMAGE, STATUS, HEALTH, EXIT, and PORTS columns.

Read logs

minibox logs a1b2c3d4

Logs are persisted to DataRoot/containers/<id>/container.log on the host.

Stop or force-kill

minibox stop a1b2c3d4   # sends SIGTERM
minibox kill a1b2c3d4   # sends SIGKILL

Remove the container record

minibox rm a1b2c3d4

Namespace isolation

Every container is launched with four Linux namespace clone flags set simultaneously:

Namespace	Clone flag	What it isolates
PID	`CLONE_NEWPID`	Process tree — container processes can only see each other
UTS	`CLONE_NEWUTS`	Hostname (set to the container ID by default)
Mount	`CLONE_NEWNS`	Filesystem tree — overlayfs rootfs is private to the container
Network	`CLONE_NEWNET`	Network interfaces, routing table, iptables rules

The parent daemon also sets CLONE_NEWIPC to isolate System V IPC resources (shared memory segments, semaphores) from the host.

After the child process enters its namespaces it chroots into the container rootfs, then mounts /proc (with hidepid=2 to prevent cross-process info leaks), a read-only /sys, and a minimal /dev tmpfs.

Cgroups v2 resource controls

MiniBox creates a cgroup slice at /sys/fs/cgroup/minibox/<containerID>/ and writes resource knobs before the workload starts. The parent slice’s cgroup.subtree_control is set to +cpu +memory +io so all three controllers are actually enforced.

cgroup file	CLI flag	Notes
`memory.max`	`-m <MB>`	Hard memory ceiling in bytes (`MB × 1 048 576`)
`cpu.max`	`-c <percent>`	`<quota> 100000` — e.g. `-c 50` writes `50000 100000`
`cpuset.cpus`	`ContainerOptions.CPUSet`	Pinned CPU set (API only, no CLI flag yet)
`io.weight`	`ContainerOptions.IOWeight`	1–1000; `db run` sets this to `800`
`/proc/self/oom_score_adj`	`ContainerOptions.OOMScoreAdj`	Adjusts OOM-killer priority; `db run` sets `-900`

To cap a container to half a CPU core and 256 MB of RAM:

minibox run -c 50 -m 256 myapp

Security hardening

MiniBox applies several layers of defence-in-depth inside the child process before executing the workload:

Capability Drop

All Linux capabilities are cleared from the ambient set (PR_CAP_AMBIENT_CLEAR_ALL) and dropped from the bounding set (PR_CAPBSET_DROP) via prctl after chroot. Containers cannot re-acquire dropped capabilities thanks to PR_SET_NO_NEW_PRIVS.

Seccomp Deny-List

A seccomp BPF filter blocks a curated deny-list of dangerous syscalls (implemented in seccomp_linux.go). The filter is installed after PR_SET_NO_NEW_PRIVS.

rlimits

Resource limits (RLIMIT_*) are applied via setrlimit to bound file descriptor counts, process counts, and core dump sizes.

hidepid=2 on /proc

/proc is mounted with hidepid=2, so container processes cannot read /proc/<pid>/ entries of other PIDs — a common info-leak vector.

MiniBox runs a root daemon. The seccomp and capability model is designed for learning and testing workloads, not untrusted multi-tenant environments. Always test in a VM before deploying to shared infrastructure.

Tiny PID 1 init / reaper

After all security controls are applied, the container does not exec the workload directly. Instead it execs a tiny init shim — /proc/self/exe init -- <cmd...> — that becomes PID 1 inside the container’s PID namespace. The init shim (RunInit() in internal/runtime/init.go) does three things:

Starts the target command as a child process.
Forwards signals received by PID 1 to the child’s process group, so SIGTERM from minibox stop propagates correctly.
Reaps zombies with wait4(-1, ...) so forked grandchildren that exit never accumulate as zombie entries.

Without this shim, any workload that forks sub-processes would leave zombie entries in the PID namespace because there would be nothing to wait on them.

Container ID format

Container IDs are exactly 8 hexadecimal characters (e.g. a1b2c3d4). The ID is printed when you run in detached mode or when you list containers with ps. Use it with every subsequent command:

minibox logs   a1b2c3d4
minibox stats  a1b2c3d4
minibox exec   a1b2c3d4 /bin/sh
minibox stop   a1b2c3d4
minibox rm     a1b2c3d4

Running interactive shells with `exec`

minibox exec enters a running container’s namespaces (using nsenter from util-linux) and runs an arbitrary command:

# Non-interactive command
minibox exec a1b2c3d4 ls -la /

# Interactive shell — requires nsenter on the host
minibox exec -it a1b2c3d4 /bin/sh

The -it flag allocates a PTY, attaches stdin/stdout/stderr to your terminal, and sets up a session leader so the shell behaves correctly. nsenter enters all six namespaces (-m -u -n -i -p plus the mount namespace).

exec runs nsenter from the host side via the daemon. It requires nsenter (part of util-linux) to be installed on the host system.

Live resource metrics with `stats`

minibox stats reads cgroup v2 metrics and host veth counters for a single container and refreshes them every second:

minibox stats a1b2c3d4

Press Ctrl+C to stop. The output shows memory usage, CPU usage, PID count, I/O bytes, and network bytes in/out.

Container states

State	Meaning
`created`	Container record registered but process not yet confirmed running
`running`	Child process is alive (verified by `kill -0 <pid>`)
`exited`	Process has exited; `EXIT` column shows the numeric exit code

State is persisted in DataRoot/state.json and survives daemon restarts. On each ps call, MiniBox performs a live kill -0 check and transitions any running container whose PID is gone to exited.

Examples

Foreground
Detached + ports
Resource limits
Custom command

# Run an interactive shell in the alpine image
minibox run alpine /bin/sh

# Run a one-shot command
minibox run alpine ls -la /

# Start a web app in the background, map host 9000 → container 80
minibox run -d -p 9000:80 myapp

# Verify it is running
minibox ps

# Tail the logs
minibox logs $(minibox ps -a | awk 'NR==2{print $1}')

# Cap to 50% of one CPU core and 512 MB of RAM
minibox run -d -c 50 -m 512 -p 8080:8080 myapp

# Watch live resource usage
minibox stats a1b2c3d4

# Override the default CMD with a custom entrypoint
minibox run -d myapp node server.js --port 3000

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Running Containers with MiniBox: Namespaces and Cgroups

Prerequisites

`minibox run` flags

Container lifecycle

Namespace isolation

Cgroups v2 resource controls

Security hardening

Capability Drop

Seccomp Deny-List

rlimits

hidepid=2 on /proc

Tiny PID 1 init / reaper

Container ID format

Running interactive shells with `exec`

Live resource metrics with `stats`

Container states

Examples

Build docs developers (and LLMs) love

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Documentation Index

​Prerequisites

​minibox run flags

​Container lifecycle

​Namespace isolation

​Cgroups v2 resource controls

​Security hardening

Capability Drop

Seccomp Deny-List

rlimits

hidepid=2 on /proc

​Tiny PID 1 init / reaper

​Container ID format

​Running interactive shells with exec

​Live resource metrics with stats

​Container states

​Examples

Build docs developers (and LLMs) love

Prerequisites

`minibox run` flags

Container lifecycle

Namespace isolation

Cgroups v2 resource controls

Security hardening

Tiny PID 1 init / reaper

Container ID format

Running interactive shells with `exec`

Live resource metrics with `stats`

Container states

Examples