Nucleus

Nucleus is a minimalist container runtime for Linux, written in Rust and published under the MIT/Apache-2.0 dual license by the sig-id organization on GitHub. It provides isolated execution environments using Linux kernel primitives directly — namespaces, cgroups v2, pivot_root, seccomp, Landlock, and capabilities — without the overhead of traditional container runtimes like Docker. The project targets two primary workloads: ephemeral AI agent sandboxes that need fast cold-start isolation, and long-running NixOS production services that require fully declarative, reproducible deployments.

What It Is

Nucleus is a single-binary container runtime that sits closer in spirit to runc or gVisor than to Docker. It drops the image-and-distribution half of the container ecosystem — there are no images, no Dockerfile, no registry pull — in exchange for deeper isolation, auditable security policy, and first-class Nix integration. The runtime supports three operating modes: agent mode (default, ephemeral fast-startup sandboxes), strict agent mode (fail-closed isolation for ephemeral workloads), and production mode (strict isolation for long-running NixOS services with declarative configuration, reproducible Nix-built root filesystems, egress policy enforcement, health checks, and systemd integration).

Architecture and Isolation Primitives

Nucleus uses Linux kernel isolation directly rather than through a daemon or socket API:

• Namespaces — PID, mount, network, UTS, IPC, user, cgroup, and optional time isolation
• cgroups v2 — CPU, memory, PIDs, and I/O resource limits
• pivot_root — Filesystem isolation (chroot fallback available only in agent mode)
• Capabilities — All capabilities dropped by default; configurable via TOML policy files
• seccomp — Syscall allowlist filtering with per-service JSON profiles and trace-based generation
• Landlock — Path-based filesystem access control via TOML policy or hardcoded defaults (Linux 5.13+)
• gVisor — Optional application kernel (runsc) with none, bridge, and gvisor-host network modes
• OCI bundle generation — Emits OCI config.json and bundle layout for gVisor, including process identity, mounts, namespaces, seccomp, hooks, and cgroup path wiring

Container filesystems are backed by tmpfs and either populated with context files (agent mode) or mounted from a pre-built Nix rootfs closure (production mode).

Nix-Native Deployment Model

Production deployments in Nucleus are built around a fully declarative model: Nix builds the root filesystem, the NixOS module declares the service, and Nucleus mounts a pinned, reproducible closure at runtime. Key integration points include:

• nucleus.lib.mkRootfs — builds a minimal, reproducible root filesystem from specified Nix packages
• nucleus.lib.mkAgentToolchainRootfs — layers a broad agent development toolchain for provider CLIs (claude, codex, gemini)
• First-class NixOS module — each container becomes a nucleus-<name>.service systemd unit with journald logging, sd_notify readiness, and automatic restart
• Flake-based packaging with pinned inputs and rootfs attestation for auditable runtime state

Performance Benchmarks

The repository publishes benchmark results comparing Nucleus against Docker and bare metal. According to the project's own benchmarks on Linux 6.18 x86_64:

• Cold start: Nucleus reports ~12 ms vs Docker's ~500 ms
• PostgreSQL 18 pgbench (SELECT-only): Nucleus with io_uring reports ~107,039 TPS vs bare metal's ~84,895 TPS
• PostgreSQL 18 pgbench (TPC-B mixed): Nucleus with worker reports ~1,757 TPS vs bare metal's ~1,490 TPS

The project notes that occasional wins over bare metal in the PostgreSQL benchmarks should be treated as benchmark noise rather than a guaranteed speedup.

Security Policy and Audit Controls

Nucleus externalizes security policy from the application build, keeping it auditable by security engineers independently of application rebuilds:

• Per-service seccomp profiles (OCI JSON format) with SHA-256 pinning
• Capability bounding set policies (TOML)
• Landlock filesystem access rules (TOML)
• Seccomp trace mode records actual syscall usage; nucleus seccomp generate creates a minimal allowlist profile
• Structured audit log, machine-readable lifecycle event streams (JSON Lines), context hashing, rootfs attestation, seccomp deny logging, mount flag verification, and kernel lockdown assertions
• Optional OpenTelemetry export for container lifecycle tracing via NUCLEUS_OTLP_ENDPOINT

Update: v0.3.3

The latest release is v0.3.3, published on April 8, 2026. The repository was last pushed on June 9, 2026, indicating active development. Recent features documented in the README include privilege drop for services (--user, --group, --additional-group), ownership-aware secrets and writable paths, OCI bundle identity support with process.user and supplementary groups, probe execution under workload identity, and systemd/NixOS service integration improvements including user, group, and supplementaryGroups exposure in the NixOS module. The project uses TLA+ formal specifications verified with the Apalache model checker across subsystems.