crate-runtime

A minimal OCI-compatible container runtime written in Rust.

Features

• Namespace isolation -- PID, mount, UTS, IPC, and network namespaces via clone()
• Cgroups v2 -- Memory, CPU, and PID limits via the unified hierarchy
• OverlayFS -- Layered filesystem with read-only and read-write modes
• OCI image pulling -- Docker Hub registry v2 API with SHA256 verification
• OCI lifecycle -- Full state machine (create/start/stop/delete) with on-disk persistence
• Bridge networking -- veth pairs, IP allocation, NAT via iptables
• Security hardening -- Capability dropping (Docker-default set), seccomp BPF filtering, path validation
• Configuration -- TOML config file with defaults for all settings

Building

cargo build --release

The binary is built as target/release/crate.

Usage

# Run a command in a new container
sudo crate run /bin/sh

# Run with a specific rootfs and hostname
sudo crate run -r /path/to/rootfs -H myhost /bin/sh

# Run with resource limits
sudo crate run --memory 512m --pids-limit 100 /bin/echo hello

# Pull an image from Docker Hub
sudo crate pull alpine:latest

# OCI lifecycle commands
sudo crate create mycontainer --bundle /path/to/bundle
sudo crate start mycontainer
sudo crate state mycontainer
sudo crate stop mycontainer
sudo crate delete mycontainer
sudo crate list

Architecture

src/
  main.rs           -- CLI entry point (clap)
  lib.rs            -- Crate root, module declarations
  error.rs          -- Error types (thiserror)
  config/           -- TOML configuration
  container/
    builder.rs      -- ContainerBuilder with validation
    process.rs      -- clone(), namespace init, exec
  namespace/
    mount.rs        -- Mount namespace, pivot_root, /proc, /dev
    pid.rs          -- PID namespace
    uts.rs          -- UTS namespace (hostname)
  cgroup/           -- Cgroups v2 (memory, CPU, PID)
  filesystem/       -- OverlayFS mount management
  image/            -- OCI registry client, content-addressable store
  network/          -- Bridge networking, veth, IP allocation
  runtime/          -- OCI lifecycle state machine
  security/         -- Capabilities, seccomp, path validation
  util/             -- Architecture detection, helpers

Security model

Containers run with reduced privileges:

• Capabilities: All capabilities are dropped except a minimal set matching Docker's defaults (14 capabilities including CAP_NET_BIND_SERVICE, CAP_CHOWN, CAP_SETUID, etc.)
• Seccomp: A BPF filter blocks dangerous syscalls (reboot, kexec_load, ptrace, bpf, mount outside namespace, kernel module operations, etc.)
• Filesystem: OverlayFS provides copy-on-write isolation. Read-only rootfs mode is supported.
• Namespaces: PID, mount, UTS, IPC, and network namespaces provide process and resource isolation.
• Cgroups: Resource limits prevent containers from consuming unbounded host resources.

Comparison to runc/crun

crate-runtime is an educational/minimal implementation. Key differences from production runtimes:

Feature	crate-runtime	runc	crun
Language	Rust	Go	C
OCI compliance	Partial	Full	Full
User namespaces	Not yet	Yes	Yes
Rootless containers	Not yet	Yes	Yes
Checkpoint/restore	No	Yes (CRIU)	Yes (CRIU)
Binary size	~5 MB	~10 MB	~100 KB

Testing

# Unit tests (no privileges needed)
cargo test --lib

# All tests including integration
make test

# Integration tests (requires Linux + root)
make test-integration

# Lint
make lint

License

MIT