{"id":47769975,"url":"https://github.com/rohansx/nullbox","last_synced_at":"2026-04-04T09:01:14.738Z","repository":{"id":347716966,"uuid":"1195024493","full_name":"rohansx/nullbox","owner":"rohansx","description":"immutable, minimal Linux OS purpose-built for AI agents. No SSH, no shell, no systemd - just microVMs, default-deny networking, and shared agent memory","archived":false,"fork":false,"pushed_at":"2026-04-02T17:23:53.000Z","size":413,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-03T13:54:04.618Z","etag":null,"topics":["agent-os","ai-agent","immutable-infrastucture","immutable-os","libkrun","linux","microvms","os","rust","security"],"latest_commit_sha":null,"homepage":"https://nullbox.sh","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rohansx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","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-29T05:35:27.000Z","updated_at":"2026-04-02T17:23:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"705d8cad-fb82-45ce-9514-6919345e1e67","html_url":"https://github.com/rohansx/nullbox","commit_stats":null,"previous_names":["rohansx/nullbox"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rohansx/nullbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohansx%2Fnullbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohansx%2Fnullbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohansx%2Fnullbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohansx%2Fnullbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rohansx","download_url":"https://codeload.github.com/rohansx/nullbox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohansx%2Fnullbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31393782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: 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":["agent-os","ai-agent","immutable-infrastucture","immutable-os","libkrun","linux","microvms","os","rust","security"],"created_at":"2026-04-03T08:53:01.954Z","updated_at":"2026-04-04T09:01:14.728Z","avatar_url":"https://github.com/rohansx.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NullBox\n\nAn immutable, minimal Linux OS purpose-built for AI agents.\n\nNo SSH. No shell. No package manager. No systemd. Just agents.\n\n## What It Is\n\nNullBox is a hardened Linux distribution where the entire OS exists to run autonomous AI agents — and nothing else. The root filesystem is read-only SquashFS. Every agent runs in its own microVM. Network access is default-deny. Secrets are AES-256-GCM encrypted at rest.\n\n## Architecture\n\n```\nEFI/BIOS → Linux 6.18 (KSPP-hardened) → initramfs → SquashFS root (read-only)\n                                                          ↓\n                                                    nulld (PID 1)\n                                                    ├── egress     — default-deny nftables firewall\n                                                    ├── ctxgraph   — shared agent memory (SQLite)\n                                                    ├── warden     — encrypted secret vault\n                                                    └── cage       — per-agent microVM (libkrun/KVM)\n                                                         ├── agent-1\n                                                         ├── agent-2\n                                                         └── ...\n```\n\n## Components\n\n| Binary | Purpose |\n|--------|---------|\n| **nulld** | PID 1 — mounts filesystems, starts services in dependency order, reaps children, handles shutdown |\n| **cage** | Spawns per-agent microVMs via libkrun (KVM), enforces CPU/memory caps, injects secrets as env vars |\n| **egress** | Default-deny network controller — agents declare allowed domains in AGENT.toml, all else is dropped |\n| **warden** | AES-256-GCM encrypted vault with PBKDF2 key derivation — secrets never touch disk in plaintext |\n| **ctxgraph** | Content-addressed shared memory (SHA-256 keys, SQLite backend) — agents share context without seeing each other |\n| **nullctl** | CLI for managing agents, vault secrets, and system status |\n\n## Kernel\n\nCustom Linux 6.18 built with Clang + ThinLTO. Key hardening:\n\n- **`CONFIG_MODULES=n`** — no loadable kernel modules, ever. Attack surface fixed at compile time.\n- **`CONFIG_IO_URING=n`** — disabled (bypasses syscall monitoring).\n- **Clang CFI** — control flow integrity via `CONFIG_CFI_CLANG=y`.\n- **KSPP defaults** — KASLR, stack protector, hardened usercopy, FORTIFY_SOURCE, zero-init allocations.\n- **Seccomp + Landlock + AppArmor** — mandatory access control stack.\n- **eBPF** — enabled for audit probes (BPF LSM).\n- **KVM** — Intel + AMD for cage microVMs.\n- **Built-in NIC drivers** — Intel (e1000e, igb, ixgbe, i40e, ice), Realtek (r8169), Broadcom (tg3, bnx2, bnxt), Mellanox, AMD, plus WiFi (iwlwifi, ath9k/10k/11k, rtw88/89).\n\n## Building\n\nRequires: Rust (nightly), Clang/LLVM, musl target, squashfs-tools, grub, xorriso.\n\n```bash\n# Install Rust musl target\nrustup target add x86_64-unknown-linux-musl\n\n# Build all binaries (static linking via musl)\ncargo build --release --target x86_64-unknown-linux-musl\n\n# Build kernel (downloads Linux 6.18, compiles with Clang)\n./kernel/scripts/build-kernel.sh\n\n# Build SquashFS root filesystem\n./image/scripts/build-squashfs.sh\n\n# Build initramfs\n./image/scripts/build-initramfs.sh\n\n# Build bootable ISO\n./image/scripts/build-iso.sh\n```\n\nThe ISO is a hybrid BIOS+EFI image (~60MB). Flash it to USB or boot in QEMU.\n\n## Installing\n\n### USB flash drive\n\n```bash\n# Find your USB device (BE CAREFUL — this erases the drive)\nlsblk\nsudo dd if=build/output/iso/nullbox.iso of=/dev/sdX bs=4M status=progress\nsync\n```\n\nBoot from USB. NullBox will auto-detect NICs via built-in drivers and attempt DHCP.\n\n### QEMU (development)\n\n```bash\nqemu-system-x86_64 \\\n    -kernel build/output/kernel/bzImage \\\n    -initrd build/output/initramfs/initramfs.cpio.gz \\\n    -append \"console=ttyS0\" \\\n    -nographic \\\n    -m 2G \\\n    -enable-kvm \\\n    -cpu host\n```\n\n### Persistent storage (optional)\n\nNullBox scans for an ext4 partition containing a `.nullbox-data` sentinel file. If found, vault secrets and ctxgraph state survive reboots.\n\n```bash\n# Create a persistent data partition\nmkfs.ext4 -L nullbox-data /dev/sdX2\nmount /dev/sdX2 /mnt\ntouch /mnt/.nullbox-data\numount /mnt\n```\n\n## Agent manifest\n\nAgents are defined in TOML:\n\n```toml\n[agent]\nname = \"researcher\"\nversion = \"0.1.0\"\n\n[capabilities]\nmax_cpu_percent = 25\nmax_memory_mb = 256\n\n[capabilities.network]\nallow = [\"api.openai.com\", \"httpbin.org\"]\n\n[capabilities.filesystem]\nread = [\"/data\"]\nwrite = [\"/data/output\"]\n```\n\nPlace manifests in `/agent/` on the SquashFS image.\n\n## CLI usage\n\n```bash\n# Start/stop agents\nnullctl start researcher\nnullctl stop researcher\nnullctl status\n\n# Manage secrets\nnullctl vault set OPENAI_KEY sk-...\nnullctl vault list\nnullctl vault delete OPENAI_KEY\n```\n\n## What doesn't exist\n\nNo cron. No dbus. No systemd. No sshd. No shell. No interactive login. No package manager. No mutable root filesystem. Six binaries in `/system/bin/`.\n\n## Smoke test\n\n```bash\n./image/scripts/smoke-test.sh\n```\n\nBoots the full image in QEMU and validates 19 checkpoints: kernel boot, filesystem mounts, nulld startup, all services running, agent microVM launch, network enforcement, and ctxgraph writes.\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohansx%2Fnullbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frohansx%2Fnullbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohansx%2Fnullbox/lists"}