GitHub - sig-id/nucleus: Lightweight OCI container runtime for NixOS

Extremely lightweight, security-hardened, declarative container runtime for agents and production services Nucleus is a minimalist container runtime for Linux. It provides isolated execution environments using Linux kernel primitives without the overhead of traditional container runtimes. For production services, it is designed 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. Nucleus supports three operating modes: Agent mode (default) – ephemeral, fast-startup sandboxes for AI agent workloads Strict agent mode – fail-closed isolation for ephemeral agent workloads without requiring production rootfs, health checks, sd_notify, or NixOS service semantics Production mode – strict isolation for long-running, network-bound NixOS services with declarative configuration, reproducible Nix-built root filesystems, egress policy enforcement, health checks, and systemd integration Production deployments are built to be: Fully declarative – service topology, runtime settings, and mounted rootfs are defined up front instead of assembled imperatively at deploy time Nix-native – first-class NixOS module support plus nucleus.lib.mkRootfs for minimal service closures Reproducible – flake-based builds, pinned store paths, and rootfs attestation keep runtime inputs stable and auditable Benchmarks Cold Start Runtime Startup Time Nucleus 12 ms Docker ~500 ms PostgreSQL 18 (pgbench, 8 clients, 60s, scale 50) In the native runtime, PostgreSQL stays near bare-metal performance under Nucleus isolation. In this harness, occasional wins over bare metal should be treated as benchmark noise rather than a guaranteed speedup. SELECT-only (read-heavy) Environment I/O Method Avg TPS Avg Latency Baremetal worker 100,222 0.080 ms Baremetal io_uring 84,895 0.096 ms Nucleus worker 105,965 0.075 ms Nucleus io_uring 107,039 0.074 ms TPC-B (mixed

read/write) Environment I/O Method Avg TPS Avg Latency Baremetal worker 1,490 5.38 ms Baremetal io_uring 1,382 5.79 ms Nucleus worker 1,757 4.55 ms Nucleus io_uring 1,585 5.05 ms Measured on Linux 6.18 x86_64. This benchmark uses the native runtime with a bind-mounted host pgdata directory and --network host, so it measures the steady-state cost of Nucleus isolation rather than VM or gVisor emulation overhead. Full results: benches/pg18_io/results/ Why Nucleus? Declarative by default for services – Production deployments are defined in NixOS and TOML rather than stitched together with ad hoc runtime scripting Deep Nix integration – First-class NixOS module, mkRootfs, and Nix store closures for minimal, locked-down service roots Reproducible service builds – Flake-based packaging, pinned inputs, and rootfs attestation make runtime state auditable and repeatable Zero-overhead isolation – Direct use of cgroups, namespaces, pivot_root, capabilities, seccomp, and Landlock Memory-backed filesystems – Container disk mapped to tmpfs, pre-populated with agent context gVisor integration – Optional application kernel for enhanced security, including networked service mode OCI runtime-spec subset for gVisor – Generates OCI bundle/config data for runsc, including process identity, mounts, namespaces, seccomp, hooks, and cgroup path wiring Detached mode – Run containers in the background as systemd transient services with --detach, managed via nucleus stop/logs/attach Production service support – Declarative NixOS module, egress policies, health checks, secrets mounting,

sd_notify, and journald integration Explicit workload identity – Native and gVisor runtimes can drop to a configured uid/gid plus supplementary groups after privileged setup Minimal rootfs – Replace host bind mounts with a purpose-built Nix store closure for production services External security policies – Per-service seccomp profiles (JSON), capability policies (TOML), and Landlock rules (TOML) with SHA-256 pinning Seccomp profile generation – Trace mode records syscalls, then nucleus seccomp generate creates a minimal allowlist profile Multi-container topologies – Compose-equivalent TOML format with dependency DAG, reconciliation, and NixOS systemd integration Integrity & audit controls – Structured audit log, machine-readable lifecycle event streams, context hashing, rootfs attestation, seccomp deny logging, mount flag verification, and kernel lockdown assertions Structured telemetry – Optional OpenTelemetry export for container lifecycle tracing Linux-native – Runs on standard Linux and NixOS Relationship to Docker Nucleus is not a drop-in Docker replacement, nor a strict subset of Docker. The feature sets overlap, but each tool does things the other does not. Nucleus is a hardened sandbox runtime (closer in spirit to runc/gVisor) that also does lightweight, declarative single-host orchestration. It drops the image-and-distribution half of Docker in exchange for deeper isolation, policy, and reproducibility. Capability Docker Nucleus Root filesystem Layered image (union mount) tmpfs directory (agent) or Nix closure (production) Images / Dockerfile / registry Yes No — no images, layers, pull/push, or OCI image spec Persistent storage Named volumes + storage drivers Ephemeral tmpfs; persistence only via explicit --volume binds Architecture dockerd daemon + socket API Single binary, direct fork/exec; detached = systemd transient unit Networking CNI plugins, overlay networks none / host / bridge only Orchestration Compose, Swarm nucleus compose (single-host TOML DAG over systemd) Default egress Allow-all outbound Deny-by-default; allow per CIDR/domain via namespace iptables

Filesystem ACLs AppArmor/SELinux profiles Landlock LSM, per-service, irreversible gVisor Optional add-on runtime First-class integrated runtime with explicit network modes Security policies Bundled defaults Externalized seccomp/caps/Landlock, SHA-256 pinned + trace-generated Reproducibility Image digests Nix closures, rootfs attestation, first-class NixOS module Verification — TLA+ specs + model-based tests across subsystems Default hardening ~300 syscalls, some caps kept All caps dropped, small seccomp allowlist, up to 8 namespaces If your mental model is "run my image instead of docker run," it will not fit: there are no images, no registry, and no persistent state. If it is "run untrusted or ephemeral workloads with stronger, auditable isolation," that is the target. Architecture Nucleus leverages Linux kernel isolation primitives: Namespaces – PID, mount, network, UTS, IPC, user, cgroup, and optional time isolation cgroups v2 – Resource limits (CPU, memory, PIDs, I/O) pivot_root – Filesystem isolation (chroot fallback available in agent mode only) Capabilities – All capabilities dropped by default, or configured via TOML policy file (irreversible) seccomp – Syscall whitelist filtering with per-service JSON profiles and trace-based generation (irreversible) Landlock – Path-based filesystem access control via hardcoded defaults or TOML policy file (Linux 5.13+) gVisor – Optional application kernel (runsc) with none, bridge handoff, and explicit gvisor-host network modes OCI bundle generation – Emits OCI config.json plus bundle layout for gVisor, including process.user, lifecycle hooks, seccomp, resource limits, and namespace mappings PID 1 init – Mini-init supervisor in production mode for zombie reaping and signal forwarding In-memory secrets – Dedicated tmpfs at /run/secrets with volatile zeroing of source buffers Mount audit – Post-setup verification of mount flags in production mode Container filesystem is backed by tmpfs and either populated with context files (agent mode) or mounted from a pre-built Nix rootfs closure (production mode). That lets production services run from a declaratively built, reproducible root filesystem instead of inheriting mutable host state.

Platform Support Linux (kernel 6.x+) on x86_64 NixOS (first-class NixOS module support) Not supported: macOS, Windows, BSDs, 32-bit Linux Installation cargo install nucleus-container Or via Nix (recommended for reproducible builds and NixOS integration): nix run github:wiggum-cc/nucleus The Cargo package name is nucleus-container; it installs the nucleus binary. The repository itself is packaged as a Nix flake, so nix run, nix build, and the NixOS module all share the same pinned inputs. Recent Features Privilege drop for services – --user, --group, and --additional-group now apply a real post-setup workload identity in both the native runtime and gVisor. Ownership-aware secrets and writable paths – Production secret staging and NixOS createHostPath = true defaults now align file ownership with the configured workload user/group. OCI bundle identity support – Generated gVisor OCI configs now carry process.user including supplementary groups, alongside namespaces, mounts, resource limits, seccomp, hooks, and cgroupsPath. Probe execution under workload identity – Exec-based health and readiness probes now run as the configured service account instead of implicitly as root. Systemd/NixOS service integration improvements – The module exposes user, group, and supplementaryGroups, and packaged Nix usage includes gvisor in the flake/dev shell path. Usage Agent Mode (default) # Run agent in isolated container with pre-populated context nucleus run --context ./agent-context/ -- /usr/bin/agent # Specify resource limits nucleus run --memory 512M --cpus 2 --context ./ctx/ -- ./agent # Name your container nucleus run --name my-agent --context ./ctx/ -- ./agent # Use gVisor for enhanced isolation nucleus run --runtime gvisor --context ./ctx/ -- ./agent # Rootless mode nucleus run --rootless -- /bin/sh # Optional networking nucleus run --network host

--allow-host-network -- curl https://example.com nucleus run --network bridge -p 8080:80 -- ./server nucleus run --network bridge -p 127.0.0.1:8080:80 -- ./server nucleus run --rootless --network bridge -- ./client nucleus run --network bridge --nat-backend userspace -- ./client # Context streaming (bind mount for instant access) nucleus run --context ./large-dir/ --context-mode bind -- ./agent # Integrity and audit hardening nucleus run --context ./ctx/ --verify-context-integrity --seccomp-log-denied -- ./agent # Environment variables nucleus run -e DEBUG=1 -- ./agent # Sensitive environment variables without argv exposure printf '{"OPENAI_API_KEY":"..."}' | nucleus run --env-fd 3 3<&0 -- ./agent # Pass sensitive values via --secret (mounted in-memory at /run/secrets) nucleus run --secret /path/to/api-key:/run/secrets/api_key -- ./agent # Run a coding agent against a stable /workspace cwd nucleus run \ --workspace "$PWD" \ --workspace-mode bind-rw \ --workspace-exec \ -- ./agent # Mount provider CLI config under the private home directory nucleus run \ --provider-config-ro "$HOME/.aws:.aws" \ --provider-config-rw "$HOME/.config/gh:.config/gh" \ -- ./agent # Run an agent with a pinned provider/toolchain rootfs instead of host runtime binds nucleus run \ --service-mode mitos-agent \ --agent-toolchain-rootfs /nix/store/...-nucleus-agent-toolchain-rootfs \ --workspace "$PWD" \ --workspace-exec \ -- codex Programmatic Launch Config nucleus run accepts the same command as nucleus create. Programmatic callers that need a stable launch contract can provide the whole request as JSON or TOML instead of constructing a long argv list: nucleus run --config ./agent.nucleus.toml nucleus run --config ./agent.nucleus.json nucleus run --config-fd 3 3<./agent.nucleus.json Config mode owns the launch request: put the workload command and all sandbox options in the config document rather than mixing them with per-option CLI flags.