Nucleus is a high-performance, minimalist container engine written in Rust. It serves as a robust demonstration of modern Linux containerization, utilizing kernel primitives like namespaces, Cgroups v2, OverlayFS, and pivot_root for secure and isolated process execution.

• True PID Isolation: Implements the "Fork-and-Wait" pattern to ensure the containerized process runs as PID 1.
• Secure Filesystem: Uses pivot_root (not just chroot) combined with private mount propagation for industry-standard isolation.
• Image Management: Support for multiple concurrent base images (Alpine, Ubuntu, Debian) with a local image store.
• Host-Driven Networking: Configures container network interfaces from the host orchestrator using nsenter, ensuring high stability and avoiding ENOMEM errors during initialization.
• Advanced Networking:
  • Automated Linux Bridge (br0) and veth pair orchestration.
  • IPAM: Automatic IP address allocation from an internal subnet.
  • Full Outbound Internet access via NAT/MASQUERADE.
  • Port Mapping: Expose container services to the host via iptables DNAT rules.
• Resource Management (Cgroups v2):
  • Memory: Support for human-readable limits (e.g., 1G, 512M) or max.
  • CPU: Granular control over CPU cycles.
  • PIDs: Prevents "fork bombs" and fork errors by managing the PIDs controller.
• Layered Storage: Implements OverlayFS with a multi-image lowerdir and a writable session layer.
• Volumes: Support for both host-path bind mounts and Named Volumes for persistent storage.
• Logging: Integrated daemonless logging for background containers.
• Rootless Mode: Supports running as an unprivileged user using User Namespaces (CLONE_NEWUSER), mapping host users to root inside the container.
• Seccomp Filtering: Integrated syscall filtering via libseccomp to restrict the attack surface of containerized processes.
• Read-only RootFS: Option to remount the entire root filesystem as read-only for enhanced security.
• Observability: Real-time resource usage statistics (CPU, Memory, PIDs) via the stats command.
• Signal Forwarding: Reliable propagation of signals (SIGINT, SIGTERM) from the host to the container's PID 1 for graceful shutdowns.
• Security Hardening: Drops dangerous Linux capabilities (e.g., CAP_SYS_RAWIO, CAP_MKNOD, CAP_SYS_PTRACE) before entering the target process.

Nucleus isn't trying to be a replacement for the entire Docker ecosystem; it's a specialized, high-performance runtime designed for systems engineers and modern infrastructure.

1. Zero-Daemon Architecture: Nucleus is a single, statically linked binary. It starts the container instantly and stays out of the way. No background daemons, no complex shims—just your process, isolated.
2. Rust-Powered Safety: Built with pure Rust, Nucleus provides memory safety without a Garbage Collector (GC). This results in a tiny memory footprint, making it ideal for high-density environments.
3. Host-Driven Stability: By configuring container networking from the host orchestrator via nsenter, Nucleus avoids initialization race conditions common in other runtimes.
4. Edge & Embedded Ready: With its minimal dependencies and small binary size (~2MB), Nucleus is the perfect "Swiss Army Knife" for isolation on resource-constrained hardware.

You can download the latest pre-built binaries for x86_64 and aarch64 from the GitHub Releases page.

• OS: Linux with Kernel 4.18+ (Cgroups v2 and OverlayFS support required).
• Tools: rustc, cargo, python3, iptables, iproute2, libseccomp-dev.
• Privileges: Root access is recommended for full networking/cgroups, but Rootless Mode is supported for unprivileged isolation.

Nucleus requires a base directory to use as the container's root. You can now pull images directly:

sudo ./target/release/Nucleus pull alpine

# IP is auto-assigned if omitted
sudo ./target/release/Nucleus run --name my-shell --image alpine /bin/sh

sudo ./target/release/Nucleus run \
 --name web-app \
 --image ubuntu \
 --ports 8080:80 \
 /bin/sh

# Named volumes are automatically created and persisted
sudo ./target/release/Nucleus run \
 --name dev-box \
 --volumes /home/user/data:/mnt/data \
 --volumes my-db-vol:/var/lib/db \
 /bin/sh

sudo ./target/release/Nucleus run \
 --name limited-box \
 --memory 512M \
 /bin/sh

./target/release/Nucleus run --rootless --name rootless-box /bin/sh

Run a container in the background and fetch its logs:

sudo ./target/release/Nucleus run --name background-task --detach --image alpine /bin/sh -c "while true; do echo 'Working...'; sleep 5; done"
sudo ./target/release/Nucleus logs background-task --follow

Mount the root filesystem as read-only to prevent any modifications:

sudo ./target/release/Nucleus run --readonly --name secure-box /bin/sh

Monitor a container's CPU, Memory, and PID usage:

sudo ./target/release/Nucleus stats my-shell --stream

./target/release/Nucleus list

sudo ./target/release/Nucleus stop my-shell

• src/main.rs: Entry point and process orchestration.
• src/args.rs: CLI argument definitions using clap.
• src/orchestrator.rs: Host-side setup (Networking, Cgroups, IPTables, nsenter config).
• src/container.rs: Inside-the-container setup (PID 1 forking, pivot_root, Capabilities).
• src/utils.rs: Shared helpers for shell commands and memory parsing.

MIT / Apache-2.0