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 or image, the NixOS module declares the service, and Nucleus mounts pinned, reproducible runtime inputs.
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/images, egress policy enforcement, health checks, and systemd integration
Production deployments are built to be:
Fully declarative – service topology, runtime settings, mounted rootfs, and optional images are defined up front instead of assembled imperatively at deploy time
Nix-native – first-class NixOS module support plus nucleus.lib.mkRootfs and nucleus.lib.mkImage for minimal service closures
Reproducible – flake-based builds, pinned store paths, rootfs attestation, and image signatures keep runtime inputs stable and auditable
The native runtime stays within run-to-run noise of bare metal, while the gVisor
runtime pays a consistent ~62% tax from the Sentry’s per-syscall user-space
emulation. 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
vs Baremetal
Baremetal
worker
170,411
0.047 ms
baseline
Baremetal
io_uring
174,026
0.046 ms
+2.1%
Nucleus
worker
169,577
0.047 ms
−0.5%
Nucleus
io_uring
172,482
0.046 ms
+1.2%
gVisor
worker
65,683
0.122 ms
−61.5%
TPC-B (mixed read/write)
Environment
I/O Method
Avg TPS
Avg Latency
vs Baremetal
Baremetal
worker
4,341
1.845 ms
baseline
Baremetal
io_uring
4,516
1.772 ms
+4.0%
Nucleus
worker
4,583
1.746 ms
+5.6%
Nucleus
io_uring
4,607
1.736 ms
+6.1%
gVisor
worker
1,655
4.834 ms
−61.9%
Measured on Linux 6.18 x86_64 with PostgreSQL 18.4. All three environments run
fully unprivileged (Nucleus rootless with --userns keep-id, no sudo);
the harness bind-mounts a host pgdata and uses host networking, so it
measures the steady-state cost of each isolation layer rather than image
unpacking or cold start. gVisor’s Sentry does not implement io_uring, so it
is measured with io_method=worker only. Full results:
[benches/pg18_io/results/]!(benches/pg18_io/results/)
Run it yourself (rootless):
Terminal window
nixshellnixpkgs#postgresql_18-c\
envROOTLESS=1SCALE=50CLIENTS=8DURATION=30RUNS=3\
bashbenches/pg18_io/bench.sh
Add GVISOR_PLATFORM=systrap if /dev/kvm is unavailable, or SKIP_GVISOR=1
to measure baremetal + native only.
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, mkImage, and Nix store closures for minimal, locked-down service roots
Reproducible service builds – Flake-based packaging, pinned inputs, rootfs attestation, and image signatures 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, credential-broker egress, 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 or Nix-built image for production services
Local image snapshots – Commit native overlay-backed containers to signed, thin image directories, then verify, inspect, and run them later
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, image signatures, seccomp deny logging, mount flag verification, and kernel lockdown assertions
Structured telemetry – Optional OpenTelemetry export for container lifecycle tracing
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 Docker’s build DSL,
registry, and distribution workflow in exchange for deeper isolation, policy,
and reproducibility. Local signed image snapshots are available, but they are
not Docker/OCI images.
Capability
Docker
Nucleus
Root filesystem
Layered image (union mount)
tmpfs directory (agent), Nix closure (production), or overlay-backed Nix closure for snapshots
Images / Dockerfile / registry
Yes
Signed local thin snapshots and Nix-built image manifests; no Dockerfile, registry, 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
All caps dropped, small seccomp allowlist, up to 8 namespaces
If your mental model is “run my Docker image instead of docker run,” it will
not fit: there is no Dockerfile, registry, pull/push lifecycle, or implicit
persistent state. Nucleus images are local signed snapshots or Nix-built
manifests over Nix rootfs closures. If your model is “run untrusted or ephemeral
workloads with stronger, auditable isolation,” that is the target.
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
Image snapshots – Local signed manifests with optional overlay diffs rooted in attested Nix rootfs closures
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). Snapshot workflows can mount that Nix rootfs with a writable native overlay and commit the overlay upperdir as a signed local image. That lets services run from declaratively built, reproducible filesystem inputs instead of inheriting mutable host state.
Or via Nix (recommended for reproducible builds and NixOS integration):
Terminal window
nixrungithub: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.
GPU passthrough – --gpu auto|nvidia|amd|intel|all binds host GPU device nodes into /dev, installs a cgroup v2 device allowlist (BPF_PROG_TYPE_CGROUP_DEVICE), relaxes the seccomp ioctl filter for vendor driver ioctls, and bind-mounts driver support files. Explicit device selection, NVIDIA env vars, and a programmatic gpu config document field are supported. See [spec/gpu-passthrough.md]!(spec/gpu-passthrough.md).
Local signed image snapshots – Native overlay-backed containers can be committed, verified, inspected, loaded, and run as thin image directories over a Nix rootfs base.
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.
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:
Terminal window
nucleusrun--config./agent.nucleus.toml
nucleusrun--config./agent.nucleus.json
nucleusrun--config-fd33<./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.
The schema uses the long CLI option names converted to snake_case:
--workspace <host-path> mounts the host project tree at /workspace. The
process cwd defaults to /workspace via --workdir /workspace.
--workspace-mode accepts:
Mode
Behavior
bind-rw
Bind mount the host path read-write at /workspace (default).
bind-ro
Bind mount the host path read-only at /workspace.
copy-in-out
Copy the host path into a private staging directory, run against that staged tree, then sync changes back after exit.
Workspace mounts are nosuid,nodev,noexec by default and native Landlock denies
execution from /workspace. Use --workspace-exec for agent-mode workflows
that build and run test binaries from the workspace. Production mode rejects
writable executable workspaces; use an immutable --rootfs and explicit policy
files for production services.
Nucleus creates a private tmpfs home at /home/agent by default and sets the
workload HOME to that path. The home tmpfs is mounted nosuid,nodev,noexec
with mode 0700 and is owned by the configured workload uid/gid. Use
--home <container-path> to choose a different private home path; the path must
be absolute and must not overlap /workspace.
Provider CLIs that require config under $HOME should use explicit provider
config mounts instead of broad host bind mounts:
--provider-config-ro SOURCE:DEST and --provider-config-rw SOURCE:DEST are
repeatable. DEST may be absolute under the configured home, or relative to the
home directory. Read-only mounts are preferred for cloud credentials; read-write
mounts are intended only for tools that must refresh local tokens.
The dedicated flag is for agent, strict-agent, and mitos-agent modes. It
uses the same read-only rootfs mount path as --rootfs, but is rejected in
production mode so production services keep using --rootfs with attestation.
Build a rootfs with the Nix helper:
nucleus.lib.mkAgentToolchainRootfs {
inheritpkgs;
providerPackages=[
# Derivations that provide claude/codex/gemini executables.
];
extraPackages=[
pkgs.rustc
pkgs.cargo
];
}
The repository also exposes packages.${system}.agent-toolchain-rootfs as a
default shell/Git/compiler/package-manager rootfs. Integrations that need exact
provider CLIs should call mkAgentToolchainRootfs with pinned provider package
derivations and pass the resulting store path to --agent-toolchain-rootfs.
Expose host GPUs to a container for CUDA, ROCm, or Mesa/Vulkan compute workloads.
GPU access is an explicit, audited privilege grant — Nucleus preserves its
full defense-in-depth stack (namespaces, capabilities, Landlock, cgroups)
while binding only the requested device nodes and relaxing only the ioctl
seccomp rule.
Terminal window
# Auto-detect and bind whatever GPU is present on the host
Device nodes — the resolved /dev/nvidia*, /dev/dri/renderD*, /dev/kfd,
/dev/nvidia-uvm*, etc. are bind-mounted into the container /dev at their
host paths and chown’d to the workload identity.
cgroup device allowlist — a BPF_PROG_TYPE_CGROUP_DEVICE program is
attached to the container cgroup, allow-listing only the base /dev nodes
plus the bound GPU devices (deny-by-default). This is best-effort: rootless
launches and kernels without bpf(2) degrade to a warning, leaving the
filesystem layer (only bound device nodes exist in /dev) as the gate.
Seccomp — the restrictive terminal-only ioctl rule is replaced with an
unconditional allow, since vendor driver ioctl request codes cannot be
enumerated. All other seccomp restrictions remain.
Driver support files — NVIDIA /proc/driver/nvidia, driver userspace
library directories, and Vulkan/ICD/EGL manifests are bind-mounted read-only
when present (--no-gpu-driver-libs skips this).
Environment — NVIDIA_VISIBLE_DEVICES, NVIDIA_DRIVER_CAPABILITIES, and
the EGL vendor manifest pointer are injected at exec time.
gVisor — runsc receives OCI linux.devices entries (major/minor/type) so
it creates the device nodes and installs the matching cgroup rules inside its
sandbox, plus bind mounts for the driver support files.
Auditing — the container_started event stream reports the vendor,
visible devices, driver capabilities, and the relaxed-seccomp flag.
--gpu is rejected in --service-mode production (declare GPU needs through an
attested rootfs instead). The same configuration is available programmatically
via the gpu field of the launch config document (--config/--config-fd).
Nucleus images are local directories containing a manifest, rootfs attestation,
store path list, optional overlay diff, and a signature for runtime-committed
images. They are not OCI/Docker images and are not pushed to or pulled from a
registry.
Terminal window
# Start an overlay-backed native container from a Nix rootfs
nucleus image commit requires a container launched with --rootfs-mode overlay; overlay rootfs mode is currently native-runtime only and production
mode rejects it. Runtime-committed images are signed with a host-local HMAC key.
Use --image-key-file PATH or set NUCLEUS_IMAGE_HMAC_KEY_FILE to pin that key
path; otherwise Nucleus creates an owner-only key under /var/lib/nucleus for
root or the user’s data directory for non-root runs. Use the same key path when
one uid commits an image and another uid, such as root, runs or inspects it.
Nix-built images from nucleus.lib.mkImage live in /nix/store and omit
image.sig because Nix store/substituter trust is the integrity root.
Runtime commits record the original command, explicit environment variables,
workdir, uid/gid, supplementary groups, and an overlay diff. The diff exporter
preserves uid/gid, mode bits, mtimes, symlinks, xattrs, POSIX ACL xattrs, and
Linux file-capability xattrs; commit fails if the caller cannot preserve
metadata. Local image signatures cover both content and preserved metadata.
nucleus image commit reads the container’s live overlay upperdir. Use
--freeze to freeze the recorded cgroup while the diff is copied; without it,
concurrent writes can be captured in a torn state. Freezing requires the
container to have a recorded cgroup path. Runtime-committed images are a
development/CLI workflow: the NixOS production module consumes build-time
mkImage images only and intentionally rejects images with overlay diffs. Image
run also constrains base.rootfs_path to a canonical /nix/store rootfs before
mounting it as the overlay lowerdir.
Image v2 is a single-rootfs plus optional single-diff directory format. There is
no layer chain, image store, registry push/pull, or ls/rm/cp image management
surface; operators manage image directories directly or use Nix store paths for
declarative production deployments.
Use -d/--detach to run a container in the background as a systemd transient service. The CLI prints the container ID and exits immediately; systemd supervises the container process.
Terminal window
# Run a container in the background
nucleuscreate-d--memory512M--/bin/sleep3600
# prints: a1b2c3d4e5f6...
# All management commands work with detached containers
The systemd transient service uses KillMode=mixed and TimeoutStopSec=30, so systemctl stop also works for graceful shutdown. The --collect flag ensures the unit is garbage-collected after the container exits.
Strict agent mode does not require a production Nix rootfs, rootfs attestation, health checks, readiness probes, sd_notify, systemd transient services, or NixOS module deployment.
Terminal window
# Run an ephemeral agent with fail-closed native isolation
Nix defines the service and the root filesystem; separate files define security policy (what the process is allowed to do at the kernel level). This separation keeps deployments declarative, security config auditable, and runtime inputs reproducible without coupling policy changes to application rebuilds.
Nucleus provides a declarative NixOS module for running containers as systemd services. Each container is managed as a nucleus-<name>.service unit with journald logging, sd_notify readiness, and automatic restart.
sdNotify=true; # Type=notify, passes NOTIFY_SOCKET into container
};
};
}
Writable bind volumes are automatically added to the generated systemd unit’s ReadWritePaths. When createHostPath = true, the NixOS module creates the host directory with systemd-tmpfiles before the container starts. If the container declares a workload user/group, those become the default tmpfiles owner for new writable paths unless the volume overrides them.
Credentials declared via credentials = [ ... ] use systemd’s credential pipeline (LoadCredential or LoadCredentialEncrypted) and are mounted into the container through Nucleus’s secret path. The CLI flag --systemd-credential NAME:DEST resolves NAME from CREDENTIALS_DIRECTORY at runtime.
For bearer-token API clients, the NixOS module exposes credentialBroker = "IP:PORT"; and credentialBrokerNoProxyEnv = true;. This maps to --credential-broker and installs broker-only egress, so leave egressAllow, egressDomains, and egress port allowlists empty when using it.
Set image = appImage; instead of rootfs = proxyRootfs; when a service should
consume a Nix-built image produced by nucleus.lib.mkImage. rootfs and
image are mutually exclusive. When command = [ ];, the module uses the image
manifest command. The NixOS production launcher currently supports build-time
images without overlay diffs; committed runtime image diffs are a local CLI
workflow.
Set user, group, and optional supplementaryGroups on a NixOS container definition when the workload should run as a dedicated service account instead of root.
Use nucleus.lib.mkRootfs to build a minimal, reproducible root filesystem:
nucleus.lib.mkRootfs {
inheritpkgs;
name="my-service-rootfs"; # optional, defaults to "nucleus-rootfs"
packages=[
my-service-package
pkgs.cacert# TLS certificates
pkgs.curl# for health checks
pkgs.busybox# minimal coreutils
];
}
This produces a Nix store path containing /bin, /lib, /etc, etc. from the specified packages. It is mounted read-only inside the container, replacing the host bind mounts used in agent mode.
mkRootfs also emits a .nucleus-rootfs-sha256 manifest at the root of the closure. Use --verify-rootfs-attestation or verifyRootfsAttestation = true; to require that manifest to match the mounted rootfs at startup.
For ephemeral provider agents, use nucleus.lib.mkAgentToolchainRootfs
instead. It layers a broad agent development toolchain on top of mkRootfs,
keeps /bin/sh and /usr/bin/env compatibility paths available, and accepts
provider CLI packages through providerPackages.
mkImage writes manifest.json, rootfs.sha256, and store-paths into a Nix
store output. Build-time images are cold and thin: the rootfs remains a Nix
store path, and the image manifest has no overlay diff unless it was produced by
the CLI nucleus image commit workflow.
Do not pass secrets via -e / --env. Environment variables are visible in /proc/<pid>/environ to any process that can read it (mitigated by hidepid=2 in production mode, but not in agent mode). Use --secret instead when a file works. If a provider CLI requires sensitive environment variables, use --env-fd FD; the fd carries a JSON object such as {"OPENAI_API_KEY":"..."} or a JSON array of KEY=VALUE strings so the values are not exposed through Nucleus argv.
Prefer credential brokers for bearer-token APIs. If untrusted code can drive a provider CLI, do not place the bearer token in the sandbox environment. Run a host-side broker that holds the credential, injects it into approved upstream requests, rate-limits and audits usage, and start Nucleus with --credential-broker IP:PORT so the sandbox can only reach that broker endpoint. Proxy environment variables are client hints, not the security boundary: Nucleus enforces the boundary with namespace-local egress rules, and non-HTTP clients that ignore proxy variables are denied unless they speak to the broker endpoint.
Protect the local image signing key. Runtime-committed image directories are verified with the host-local HMAC key selected by NUCLEUS_IMAGE_HMAC_KEY_FILE or the default owner-only key path. Treat that file like deployment signing material: do not share it across trust domains unless those hosts should be able to trust and produce each other’s local image snapshots.
Privilege dropping is explicit. Nucleus must start with elevated privileges to create namespaces, mount filesystems, and configure cgroups/networking. Use --user / --group (or the NixOS module’s user / group options) so the workload itself does not continue running as root after setup. In production mode, staged secrets under /run/secrets are re-owned to that workload identity.
Agent mode is not hardened. By design, agent mode applies several security mechanisms on a best-effort basis: seccomp and Landlock failures are warn-and-continue (with --allow-degraded-security), chroot fallback is available (with --allow-chroot-fallback), bridge DNS defaults to public resolvers (8.8.8.8), and cgroup creation failures are non-fatal. Operators requiring strict isolation for ephemeral workloads should use --service-mode strict-agent; operators deploying long-running NixOS services should use production mode.
Native host forbidden; gvisor-host allowed with gVisor + explicit opt-in
Native host forbidden; gvisor-host allowed with gVisor + explicit opt-in
Cgroup limits
Best-effort
Required (fatal on create/apply failure)
Required (fatal on create/apply failure)
Bridge DNS
Defaults to 8.8.8.8/8.8.4.4
Must be configured explicitly unless credential broker mode disables DNS
Must be configured explicitly unless credential broker mode disables DNS
Rootfs
Host bind mounts unless --rootfs (optionally with --rootfs-mode overlay) or --agent-toolchain-rootfs is supplied
Host bind mounts unless --rootfs (optionally with --rootfs-mode overlay) or --agent-toolchain-rootfs is supplied
Pre-built Nix closure (--rootfs) or build-time mkImage image without an overlay diff
Workspace
Optional /workspace; bind/copy-in-out for agents
Optional /workspace; bind/copy-in-out for agents
Optional, non-executable unless read-only or policy-specific
Egress policy
Optional
Optional
Deny-all default where enforceable; unavailable with gvisor-host
Memory limit
Optional
Optional
Required
PID 1 init
Direct exec
Direct exec
Mini-init with zombie reaping + signal forwarding
Workload uid/gid
Root by default
User namespace remapping required when running as host root
Configurable post-setup drop via --user / --group
Secrets
In-memory tmpfs
In-memory tmpfs
In-memory tmpfs with volatile zeroing
/proc
Mounted normally
Mounted normally
hidepid=2 (hides other processes)
Mount audit
Skipped
Skipped
Post-setup flag verification (fatal)
Seccomp trace mode
Allowed
Forbidden
Forbidden
Landlock ABI
Best-effort
Full enforcement required on native
V3 minimum required
Health checks
Optional
Optional
Optional
sd_notify
Optional
Optional
Optional
Security policies
Optional
Optional
Optional (recommended)
Overlay rootfs mode is a writable development snapshot mode, not the strict
production posture. To support overlayfs copy-up, Nucleus retains
CAP_DAC_OVERRIDE and CAP_FOWNER in the workload and grants native Landlock
read/write/execute access to /. Use bind rootfs mode for the default-deny
Landlock and all-capabilities-dropped posture.
When production bridge mode runs without --egress-allow or --egress-domain, Nucleus installs a strict deny-all OUTPUT policy, including DNS.
When --egress-allow or --egress-domain is specified, Nucleus applies iptables OUTPUT chain rules inside the container’s network namespace:
Allow loopback traffic
Allow established/related connections
Allow DNS to configured resolvers
Resolve permitted domains to IPv4 /32 rules at startup
Allow traffic to permitted CIDRs and resolved domain addresses (optionally restricted to specific ports)
Domain egress entries are exact DNS names, not wildcard or suffix rules. Nucleus resolves each domain with the supervisor host resolver before installing the namespace-local iptables policy, keeps only IPv4 answers, and fails startup if a domain has no IPv4 address. Long-running services that depend on provider IP rotation should restart after DNS changes, use provider-published CIDR ranges, or route traffic through a stable internal proxy and allow that proxy CIDR instead.
--credential-broker IP:PORT is the first-class Nucleus path for bearer-token API clients that must run inside an untrusted sandbox. The actual broker process is host-side and outside Nucleus: it owns the real secret, authenticates outbound requests, enforces upstream method/path/destination limits, and writes the audit log. Nucleus enforces the sandbox side by installing a deny-by-default policy that allows only TCP to the broker /32 and disables DNS from the sandbox.
Terminal window
# Broker listens on the host side of the bridge, for example 10.0.42.1:8080.
# Nucleus injects HTTP_PROXY/HTTPS_PROXY values pointing at that endpoint.
Broker mode is mutually exclusive with --egress-allow, --egress-domain, --egress-tcp-port, and --egress-udp-port; adding direct routes would defeat the broker boundary. The broker endpoint must be the host-side IPv4 bridge gateway, not 127.0.0.1, because loopback is local to the container namespace. The default host-side bridge gateway is 10.0.42.1; Nucleus rejects broker IPs that differ from the configured bridge gateway.
Credential broker mode currently requires the kernel bridge/veth/iptables NAT backend. It rejects explicit --nat-backend userspace, and --nat-backend auto is rejected when it would resolve to userspace NAT for rootless/native containers. slirp4netns does not expose the host-side bridge gateway as a host-bound address for the broker.
At startup, Nucleus performs a short TCP pre-connect to the broker endpoint after bridge setup and before releasing the workload. A missing or unreachable broker fails the sandbox start immediately instead of letting the first outbound request hang.
When broker mode is enabled, Nucleus injects NUCLEUS_CONTAINER_ID and NUCLEUS_CREDENTIAL_BROKER_TOKEN into the workload. The token is an independent random per-container value, so a broker or provider-specific wrapper can authenticate and attribute requests by sandbox. User-provided values for those keys are overwritten in broker mode.
--credential-broker-no-proxy-env disables automatic HTTP_PROXY/HTTPS_PROXY injection. The shorter alias --no-broker-proxy-env is also accepted.
A dependency-free reference broker is available at examples/credential_broker.rs. It audits CONNECT requests and forwards them as opaque tunnels, and it injects a static Authorization: Bearer ... header for plain HTTP absolute-form proxy requests. CONNECT over TLS cannot have upstream bearer headers injected unless the broker terminates TLS or the client uses a provider-specific base URL/protocol that lets the broker see the HTTP request.
When using gVisor (--runtime gvisor), the network mode is selected explicitly:
Container --network
gVisor --network flag
Description
none
none
Fully isolated (default for agents)
bridge
host
Nucleus prepares a bridge/userspace NAT namespace, then runsc inherits it
gvisor-host
host
gVisor hostinet mode; omits the OCI network namespace and requires --allow-host-network
The gvisor-host mode is intentionally separate from native host networking. Native host remains a direct host namespace mode. gvisor-host keeps the gVisor runtime boundary, but weakens network isolation by letting runsc hostinet use the host network stack. Because there is no Nucleus-owned network namespace in this mode, Nucleus egress policy is unavailable with gvisor-host.
--terminal runs the workload behind a pseudoterminal. Supplying
--console-socket <path> implies terminal mode and follows the OCI console
socket convention: the runtime connects to the AF_UNIX socket and sends the PTY
master file descriptor with SCM_RIGHTS.
Native containers allocate the PTY directly. The workload process becomes a
session leader, the PTY slave becomes its controlling TTY, and stdin/stdout/stderr
all point at that slave. gVisor containers set process.terminal = true and
process.consoleSize in the generated OCI config, then pass --console-socket
through to runsc.
Console bytes are not decoded or rewritten by Nucleus. Clients such as
mitos/libghostty are expected to parse and render the raw stream. Window resizing
uses PTY window-size ioctls; foreground SIGWINCH is also forwarded to the
container process.
Nucleus is not a generic external OCI runtime. For gVisor execution it generates an OCI bundle layout and config.json that follow the OCI runtime-spec fields Nucleus uses in practice.
hooks: OCI lifecycle hooks with OCI state JSON on stdin
annotations: runtime metadata passed through to the bundle
That OCI path is the contract used with runsc. The native runtime uses Nucleus’s direct Linux setup path rather than exposing a separate OCI CLI surface.
Lifecycle hooks execute host-side commands with supervisor privileges. They are not accepted in topology service definitions; use only explicit administrative nucleus create --hooks configuration for hooks.
Use --events-jsonl <path> to write control-plane lifecycle events as JSON Lines, or --events-fd <fd> to write them to an inherited file descriptor. The stream is separate from workload stdout/stderr and PTY bytes; operators can consume it without parsing user process output. --events-fd rejects stdio descriptors and is not available with --detach; use --events-jsonl for detached containers.
Events include a container start record and a final summary record. The records carry the container ID, PID, cgroup path, workspace/context mount, network mode, seccomp mode, Landlock status, capability status, resource limits, exit status, resource stats, and whether cleanup succeeded.
benches/container_runtime.rs compares the same workloads when run directly on the host vs inside a native Nucleus container. The matrix covers:
cold startup (/bin/sh -lc ':')
a CPU-bound shell arithmetic loop
context-heavy file scans with both bind-mounted and copied context
a constrained profile that applies the same cgroup limits to the direct host process and the containerized process
Because the benchmark creates namespaces and cgroups, it must run as root
(sudo -E cargo bench --bench container_runtime). The system-level pg18_io
benchmark additionally supports an unprivileged path — see
[benches/pg18_io/]!(benches/pg18_io/) (ROOTLESS=1).
Terminal window
sudo-Ecargobench--benchcontainer_runtime
Criterion writes the comparison reports to target/criterion/container_runtime/.
[
]!(#license)