MARKDOWN SOURCE
# mini-container `mini-container` is a small, intentionally incomplete Linux container runtime for learning how kernel primitives fit together. It uses Linux syscalls and `/proc`/cgroup files directly; it does not call Docker, Podman, `nsenter`, `chroot`, or other container/helper programs. > **Safety warning:** this is an educational demonstration, not a security boundary for hostile workloads. It does not install a seccomp filter, drop capabilities inside the container user namespace, set a read-only root, provide a complete `/dev` or `/proc`, or comprehensively validate the root filesystem. Do not run untrusted payloads with it. A user namespace limits privilege in the parent namespace but does not make kernel vulnerabilities harmless. ## Requirements - Linux 5.9 or newer with user, mount, UTS, IPC, PID, and network namespaces enabled (`close_range(2)` is used to prevent inherited host file descriptors leaking into the payload). - Permission to create an unprivileged user namespace, or sufficient privileges for the requested namespaces and mount/chroot operations. - A **delegated, writable cgroup v2 directory** with the `memory` and `pids` controllers available and enabled for child cgroups. The runtime will not remount cgroups, change controller ownership, or try to make a system cgroup hierarchy writable. - A root filesystem containing the requested executable and all of its runtime dependencies. The program does not mount `/proc`, `/sys`, `/dev`, or bind mounts into it. Check your distribution's documentation for how to delegate a cgroup v2 subtree to your user. On some systems unprivileged user namespaces or cgroup delegation are disabled; in that case the program fails rather than falling back to a less isolated mode. Do not run it with `sudo` as a workaround without understanding the effects. ### Privileges and capabilities By default the launcher asks the kernel to create a new user namespace together with the other namespaces, then maps container UID/GID 0 to the invoking effective UID/GID. With unprivileged user namespaces permitted, no host-root capability is intentionally required for the namespace, mount-propagation, hostname, or chroot steps: the child receives capabilities scoped to its new user namespace (including the `CAP_SYS_ADMIN` operations for its mount/UTS namespaces and `CAP_SYS_CHROOT` for `chroot(2)`). The parent still needs permission to write the one-ID maps and must have write access to the delegated cgroup controls. If host policy disallows this unprivileged user-namespace setup, the runtime fails; it does not silently switch modes. Kernel policy may vary, so this is not a promise that the process can run on every host. ## Build and test Rust `1.98.1` is pinned in `mise.toml`; the only crate dependency is pinned exactly in `Cargo.toml`, with resolved versions in `Cargo.lock`. ```sh mise install mise run install mise run check ``` `mise run check` runs formatting verification, unprivileged unit tests, and Clippy over all targets/features with `all` and `pedantic` warnings treated as errors. Tests exercise argument validation only; they never create namespaces or cgroups. `mise run run -- --help` prints CLI help without launching a workload. ## CLI ```text mini-container --rootfs DIR [OPTIONS] -- /ABSOLUTE/COMMAND [ARGS...] --rootfs DIR Root filesystem directory (required) --cgroup-parent DIR Writable delegated cgroup v2 directory (default /sys/fs/cgroup) --memory BYTES memory.max limit (default 268435456) --pids COUNT pids.max limit (default 64) --hostname NAME UTS namespace hostname (default mini-container) -h, --help Show help ``` Arguments after `--` are passed directly as the payload's argv; no shell is started implicitly and shell metacharacters are not interpreted. The executable path must be absolute **inside** the root filesystem. For example, with a prepared rootfs and a delegated cgroup directory: ```sh cargo run --locked -- \ --rootfs ./rootfs \ --cgroup-parent "$HOME/my-delegated-cgroup" \ --memory 134217728 --pids 32 \ -- /bin/sh -c 'exec /bin/echo hello from the container' ``` The runtime creates a uniquely named child cgroup, writes `memory.max` and `pids.max`, then clones a child into new user, mount, UTS, IPC, PID, and network namespaces. While that child waits on a pipe, the parent writes its UID/GID maps and places it in the cgroup. Only then is the child released to make mount propagation private, set its hostname, change into the selected root, call `chroot(2)`, and `execv(3)` the payload. Child status is returned to the caller. The runtime leaves an occupied cgroup in place and reports cleanup errors rather than killing other processes that may remain in it. ## Scope and limitations - Root inside the new user namespace maps to the invoking effective UID/GID. Namespace setup still depends on kernel policy and can be prohibited by the host. - Network access is isolated in a new network namespace; no interfaces or routes are configured. - The payload is PID 1 in its PID namespace. This MVP does not forward signals or reap arbitrary orphaned descendants like a production init process. - Resource controls require a cgroup v2 hierarchy delegated to the caller. The default hierarchy path may be read-only or unavailable; pass a delegated path with `--cgroup-parent`. - No mounts are made inside rootfs. A dynamically linked program must have its interpreter and libraries available there; shell scripts need their interpreter as well. - There is no seccomp, capability policy, syscall filtering, device policy, networking setup, image management, or production-grade defense against hostile inputs. Run payloads only on a disposable Linux system or VM where you understand the namespace and cgroup configuration. Privileged/manual integration testing is deliberately not part of `mise run check`.
mini-container
mini-container is a small, intentionally incomplete Linux container runtime for learning how kernel primitives fit together. It uses Linux syscalls and /proc/cgroup files directly; it does not call Docker, Podman, nsenter, chroot, or other container/helper programs.
Safety warning: this is an educational demonstration, not a security boundary for hostile workloads. It does not install a seccomp filter, drop capabilities inside the container user namespace, set a read-only root, provide a complete
/devor/proc, or comprehensively validate the root filesystem. Do not run untrusted payloads with it. A user namespace limits privilege in the parent namespace but does not make kernel vulnerabilities harmless.
Requirements
- Linux 5.9 or newer with user, mount, UTS, IPC, PID, and network namespaces enabled (
close_range(2)is used to prevent inherited host file descriptors leaking into the payload). - Permission to create an unprivileged user namespace, or sufficient privileges for the requested namespaces and mount/chroot operations.
- A delegated, writable cgroup v2 directory with the
memoryandpidscontrollers available and enabled for child cgroups. The runtime will not remount cgroups, change controller ownership, or try to make a system cgroup hierarchy writable. - A root filesystem containing the requested executable and all of its runtime dependencies. The program does not mount
/proc,/sys,/dev, or bind mounts into it.
Check your distribution's documentation for how to delegate a cgroup v2 subtree to your user. On some systems unprivileged user namespaces or cgroup delegation are disabled; in that case the program fails rather than falling back to a less isolated mode. Do not run it with sudo as a workaround without understanding the effects.
Privileges and capabilities
By default the launcher asks the kernel to create a new user namespace together with the other namespaces, then maps container UID/GID 0 to the invoking effective UID/GID. With unprivileged user namespaces permitted, no host-root capability is intentionally required for the namespace, mount-propagation, hostname, or chroot steps: the child receives capabilities scoped to its new user namespace (including the CAP_SYS_ADMIN operations for its mount/UTS namespaces and CAP_SYS_CHROOT for chroot(2)). The parent still needs permission to write the one-ID maps and must have write access to the delegated cgroup controls. If host policy disallows this unprivileged user-namespace setup, the runtime fails; it does not silently switch modes. Kernel policy may vary, so this is not a promise that the process can run on every host.
Build and test
Rust 1.98.1 is pinned in mise.toml; the only crate dependency is pinned exactly in Cargo.toml, with resolved versions in Cargo.lock.
mise install
mise run install
mise run check
mise run check runs formatting verification, unprivileged unit tests, and Clippy over all targets/features with all and pedantic warnings treated as errors. Tests exercise argument validation only; they never create namespaces or cgroups. mise run run -- --help prints CLI help without launching a workload.
CLI
mini-container --rootfs DIR [OPTIONS] -- /ABSOLUTE/COMMAND [ARGS...]
--rootfs DIR Root filesystem directory (required)
--cgroup-parent DIR Writable delegated cgroup v2 directory (default /sys/fs/cgroup)
--memory BYTES memory.max limit (default 268435456)
--pids COUNT pids.max limit (default 64)
--hostname NAME UTS namespace hostname (default mini-container)
-h, --help Show help
Arguments after -- are passed directly as the payload's argv; no shell is started implicitly and shell metacharacters are not interpreted. The executable path must be absolute inside the root filesystem. For example, with a prepared rootfs and a delegated cgroup directory:
cargo run --locked -- \
--rootfs ./rootfs \
--cgroup-parent "$HOME/my-delegated-cgroup" \
--memory 134217728 --pids 32 \
-- /bin/sh -c 'exec /bin/echo hello from the container'
The runtime creates a uniquely named child cgroup, writes memory.max and pids.max, then clones a child into new user, mount, UTS, IPC, PID, and network namespaces. While that child waits on a pipe, the parent writes its UID/GID maps and places it in the cgroup. Only then is the child released to make mount propagation private, set its hostname, change into the selected root, call chroot(2), and execv(3) the payload. Child status is returned to the caller. The runtime leaves an occupied cgroup in place and reports cleanup errors rather than killing other processes that may remain in it.
Scope and limitations
- Root inside the new user namespace maps to the invoking effective UID/GID. Namespace setup still depends on kernel policy and can be prohibited by the host.
- Network access is isolated in a new network namespace; no interfaces or routes are configured.
- The payload is PID 1 in its PID namespace. This MVP does not forward signals or reap arbitrary orphaned descendants like a production init process.
- Resource controls require a cgroup v2 hierarchy delegated to the caller. The default hierarchy path may be read-only or unavailable; pass a delegated path with
--cgroup-parent. - No mounts are made inside rootfs. A dynamically linked program must have its interpreter and libraries available there; shell scripts need their interpreter as well.
- There is no seccomp, capability policy, syscall filtering, device policy, networking setup, image management, or production-grade defense against hostile inputs.
Run payloads only on a disposable Linux system or VM where you understand the namespace and cgroup configuration. Privileged/manual integration testing is deliberately not part of mise run check.