{"id":47735304,"url":"https://github.com/sumant1122/nucleus","last_synced_at":"2026-04-05T00:01:39.023Z","repository":{"id":347771262,"uuid":"1195215996","full_name":"sumant1122/Nucleus","owner":"sumant1122","description":"A high-performance, minimalistic container engine in Rust.","archived":false,"fork":false,"pushed_at":"2026-04-02T13:38:04.000Z","size":34,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T07:06:22.039Z","etag":null,"topics":["cgroups-v2","container-runtime","containers","devops-tools","docker-alternative","edge-computing","embedded-linux","faas","linux-kernel","namespaces","oci","overlayfs","pivot-root","rust","security","systems-programming","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumant1122.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T11:42:47.000Z","updated_at":"2026-04-02T13:38:08.000Z","dependencies_parsed_at":"2026-03-29T15:07:28.189Z","dependency_job_id":null,"html_url":"https://github.com/sumant1122/Nucleus","commit_stats":null,"previous_names":["sumant1122/nucleus"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sumant1122/Nucleus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumant1122%2FNucleus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumant1122%2FNucleus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumant1122%2FNucleus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumant1122%2FNucleus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumant1122","download_url":"https://codeload.github.com/sumant1122/Nucleus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumant1122%2FNucleus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31381007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T21:40:47.592Z","status":"ssl_error","status_checked_at":"2026-04-03T21:40:05.436Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cgroups-v2","container-runtime","containers","devops-tools","docker-alternative","edge-computing","embedded-linux","faas","linux-kernel","namespaces","oci","overlayfs","pivot-root","rust","security","systems-programming","virtualization"],"created_at":"2026-04-02T22:27:42.490Z","updated_at":"2026-04-03T23:01:00.248Z","avatar_url":"https://github.com/sumant1122.png","language":"Rust","readme":"# Nucleus ⚛️\n**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.\n\n## Key Features\n- **True PID Isolation**: Implements the \"Fork-and-Wait\" pattern to ensure the containerized process runs as **PID 1**.\n- **Secure Filesystem**: Uses `pivot_root` (not just `chroot`) combined with private mount propagation for industry-standard isolation.\n- **Host-Driven Networking**: Configures container network interfaces from the host orchestrator using `nsenter`, ensuring high stability and avoiding `ENOMEM` errors during initialization.\n- **Advanced Networking**: \n    - Automated Linux Bridge (`br0`) and `veth` pair orchestration.\n    - Full Outbound Internet access via NAT/MASQUERADE.\n    - **Port Mapping**: Expose container services to the host via `iptables` DNAT rules.\n- **Resource Management (Cgroups v2)**:\n    - **Memory**: Support for human-readable limits (e.g., `1G`, `512M`) or `max`.\n    - **CPU**: Granular control over CPU cycles.\n    - **PIDs**: Prevents \"fork bombs\" and fork errors by managing the PIDs controller.\n- **Layered Storage**: Implements OverlayFS with a read-only base image and a writable session layer.\n- **Rootless Mode**: Supports running as an unprivileged user using User Namespaces (`CLONE_NEWUSER`), mapping host users to `root` inside the container.\n- **Seccomp Filtering**: Integrated syscall filtering via `libseccomp` to restrict the attack surface of containerized processes.\n- **Read-only RootFS**: Option to remount the entire root filesystem as read-only for enhanced security.\n- **Security Hardening**: Drops dangerous Linux capabilities (e.g., `CAP_SYS_RAWIO`, `CAP_MKNOD`, `CAP_SYS_PTRACE`) before entering the target process.\n\n---\n\n## Why Nucleus? 🚀\n\nNucleus 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.\n\n### The Advantage\n1.  **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.\n2.  **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.\n3.  **Host-Driven Stability:** By configuring container networking from the host orchestrator via `nsenter`, Nucleus avoids initialization race conditions common in other runtimes.\n4.  **Edge \u0026 Embedded Ready:** With its minimal dependencies and small binary size (~2MB), Nucleus is the perfect \"Swiss Army Knife\" for isolation on resource-constrained hardware.\n\n### Comparison: Nucleus vs. The Industry\n\n| Feature | Docker / Podman | Nucleus |\n| :--- | :--- | :--- |\n| **Binary Size** | Huge (100MB+) | Tiny (~2MB) |\n| **Startup Time** | Slow (~500ms+) | Instant (~10-20ms) |\n| **Runtime** | Go (Garbage Collected) | Rust (Zero-overhead) |\n| **Dependencies** | Many (iptables, dbus, etc.) | Minimal (Kernel primitives) |\n| **Architecture** | Daemon-based | Zero-daemon / Standalone |\n| **Use Case** | General App Dev | Edge, FaaS, Security, Embedded |\n\n---\n\n## 🚀 Getting Started\n\n### 1. Download Pre-built Binaries\nYou can download the latest pre-built binaries for **x86_64** and **aarch64** from the [GitHub Releases](https://github.com/sumant1122/Nucleus/releases) page.\n\n### 2. Prerequisites\n- **OS**: Linux with Kernel 4.18+ (Cgroups v2 and OverlayFS support required).\n- **Tools**: `rustc`, `cargo`, `python3`, `iptables`, `iproute2`, `libseccomp-dev`.\n- **Privileges**: Root access is recommended for full networking/cgroups, but **Rootless Mode** is supported for unprivileged isolation.\n\n### 3. Prepare a RootFS\nNucleus requires a base directory to use as the container's root. Use the helper script to fetch a minimal Alpine Linux image:\n```bash\npython3 pull_image.py alpine\n```\n\n### 4. Build Nucleus (Optional)\nIf you prefer building from source:\n```bash\ncargo build --release\n```\n\n---\n\n## 🛠 Usage Examples\n\n### Run a basic isolated shell\n```bash\nsudo ./target/release/Nucleus --name my-shell --ip 10.0.0.10 /bin/sh\n```\n\n### Expose a Web Server (Port Mapping)\nExpose a container's port 80 to the host's port 8080:\n```bash\nsudo ./target/release/Nucleus \\\n  --name web-app \\\n  --ip 10.0.0.20 \\\n  --ports 8080:80 \\\n  /bin/sh\n```\n\n### Mount Host Directories (Volumes)\n```bash\nsudo ./target/release/Nucleus \\\n  --name dev-box \\\n  --ip 10.0.0.30 \\\n  --volumes /home/user/data:/mnt/data \\\n  /bin/sh\n```\n\n### Resource-Limited Environment\n```bash\nsudo ./target/release/Nucleus \\\n  --name limited-box \\\n  --ip 10.0.0.40 \\\n  --memory 512M \\\n  /bin/sh\n```\n\n### Unprivileged Rootless Execution\nRun Nucleus without root privileges using User Namespaces:\n```bash\n./target/release/Nucleus --rootless --name rootless-box --ip 10.0.0.50 /bin/sh\n```\n\n### Secure Read-only Environment\nMount the root filesystem as read-only to prevent any modifications:\n```bash\nsudo ./target/release/Nucleus --readonly --name secure-box --ip 10.0.0.60 /bin/sh\n```\n\n---\n\n## 📂 Project Structure\n- `src/main.rs`: Entry point and process orchestration.\n- `src/args.rs`: CLI argument definitions using `clap`.\n- `src/orchestrator.rs`: Host-side setup (Networking, Cgroups, IPTables, `nsenter` config).\n- `src/container.rs`: Inside-the-container setup (PID 1 forking, `pivot_root`, Capabilities).\n- `src/utils.rs`: Shared helpers for shell commands and memory parsing.\n\n## ⚖️ License\nMIT / Apache-2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumant1122%2Fnucleus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumant1122%2Fnucleus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumant1122%2Fnucleus/lists"}