hippobox 0.3.0

Lightweight Linux container manager using raw Linux primitives
hippobox-0.3.0 is not a library.

hippobox

CI Crates.io License

A lightweight Linux container manager written in Rust. Pulls OCI images from any registry, sets up an isolated container using raw Linux primitives, and runs your command. No runc, containerd, or other runtime wrappers involved.

Note: hippobox is an experimental project built for learning and exploration. It is not intended for production use. If you need a production container runtime, use Docker, Podman, or a similar tool.

Features

  • Pull images from any OCI-compliant registry (Docker Hub, GHCR, etc.)
  • Run containers with full namespace isolation (mount, UTS, IPC, PID, network)
  • Rootless mode with automatic user namespace setup
  • Overlayfs-backed container filesystems with per-container writable layers
  • Port forwarding via pasta (from the passt project)
  • Volume mounts (bind mounts, read-only support)
  • Environment variable overrides
  • Seccomp BPF filtering and /proc path masking
  • Automatic image caching and layer deduplication
  • Containers are always temporary and cleaned up on exit

The release binary is around 2 MB.

Installation

From crates.io

cargo install hippobox

This installs the hippobox binary only. The optional librename_shim.so (used for rootless EXDEV workaround) is not included. Use a pre-built release if you need the shim.

Pre-built binary

Download the latest release from the GitHub Releases page. The archive includes both the statically linked hippobox binary and librename_shim.so. Place them in the same directory for the rootless EXDEV workaround to be active.

Requirements

  • Linux (x86_64), tested under WSL2
  • Kernel 5.11+ for rootless overlayfs support
  • cgroup v2 for rootful mode
  • unshare from util-linux for rootless bootstrap
  • pasta from passt for port forwarding (-p)

hippobox is Linux-only. It will not run on macOS or Windows outside of WSL.

Usage

# Pull an image
hippobox pull docker.io/nginx:latest

# Run a container (auto-pulls if not cached)
hippobox run docker.io/nginx:latest

# Run with a custom command
hippobox run docker.io/nginx:latest /bin/sh -c "echo hello"

# Environment overrides
hippobox run --env POSTGRES_HOST_AUTH_METHOD=trust docker.io/postgres:16-alpine

# Volume mounts
hippobox run -v /host/data:/data:ro docker.io/alpine:latest ls /data

# Port forwarding
hippobox run -p 8080:80 docker.io/nginx:latest

# List cached images
hippobox images

# Clean all cached images and layers
hippobox clean

Images require an explicit registry prefix (docker.io/, ghcr.io/, etc).

If you run hippobox as a non-root user, it automatically switches to rootless mode.

Building

cargo build --release

Contributing

Set up the pre-commit hook after cloning:

git config core.hooksPath .githooks

This runs cargo fmt --check and cargo clippy before each commit.

You can also run the checks manually:

cargo fmt --check -p hippobox
cargo clippy -p hippobox -- -D warnings
cargo test -p hippobox

Rootless Mode

Rootless mode is automatic. If hippobox is not running as root, it bootstraps through a user namespace via unshare.

What changes in rootless mode:

  • cgroups are skipped
  • /proc is bind-mounted from the host so /dev/stderr and friends work
  • /sys stays out of the container
  • /dev device nodes are bind-mounted from a staging directory inside the rootfs
  • Directory renames work via an LD_PRELOAD shim that handles EXDEV transparently

Host requirements for rootless:

  • Linux user namespaces must be enabled
  • unshare from util-linux must be installed
  • /etc/subuid and /etc/subgid should provide a subordinate ID range for your user
  • newuidmap and newgidmap from util-linux should be available

Limitations:

  • Rootless containers cannot bind privileged ports unless the host allows it
  • The rename shim covers dynamically-linked binaries only (statically-linked Go/Rust binaries with directory renames may still see EXDEV)
  • Rootless mode is not a production isolation boundary

Roadmap

  • Pre-built release binaries for x86_64
  • Publish to crates.io
  • Multi-architecture builds (ARM64, etc.)
  • Integration tests against release binaries in CI
  • hippobox ps and hippobox exec
  • Configurable resource limits (--memory, --cpus, --pids)
  • Digest-based image refs (image@sha256:...)
  • Auth for private registries
  • Bridge networking with NAT
  • zstd layer support

Licence

Licensed under either of

at your option.