{"id":"9419da5b-8a2b-49ba-bddf-6e52175c69ed","slug":"hivebox","kind":"mcp","name":"hivebox","summary":"Lightweight Linux sandbox for AI agents. Kernel-native isolation (namespaces, cgroups, seccomp, Landlock) with REST API, MCP bridge, and web dashboard. Single Rust binary.","owner":"TetiAI","repoUrl":"https://github.com/TetiAI/hivebox","license":"BSD-3-Clause","licenseTier":"permissive","trust":"community","stars":61,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T05:15:22.930Z","logoUrl":"https://avatars.githubusercontent.com/u/190756499?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics","memory-knowledge"],"tags":["agent-sandbox","ai-agents","ai-infrastructure","cli","devtools","linux","linux-sandbox","multi-tenant"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T07:03:09.044Z","sample":false,"url":"https://conduits.dev/tools/hivebox","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

\n \"HiveBox\"\n

\n

\n \"TetiAI\" by TetiAI\n

\n\n**Native Linux sandboxing built for the AI era.**\n\nHiveBox turns Linux into a platform where sandboxing is a first-class primitive. No containers, no VMs — just direct kernel isolation (namespaces, cgroups, seccomp, Landlock) exposed through a simple CLI and REST API.\n\nEach **hivebox** is a lightweight, isolated Linux sandbox with its own [OpenCode](https://opencode.ai) AI agent. Launch thousands on a single host — each running arbitrary commands in complete isolation with near-zero overhead, and each with a dedicated AI coding assistant accessible via API or the built-in web dashboard.\n\n![HiveBox Dashboard](assets/screen.png)\n\n## Stop sandboxing everything.\n\nThe AI industry has a proportionality problem. Every major platform spins up full Ubuntu containers — mounted filesystems, browsers, CLI tools, isolated networks — for every user interaction. A .pptx, a .docx, a .xlsx, a PDF, a CSV export. Tasks that take milliseconds with a lightweight library are burning entire virtual machines in the cloud.\n\nTo generate a 10-slide presentation, a small virtual computer boots. To format a Word document with headers, a container spins up. To create a spreadsheet with a few formulas, an isolated network is allocated. None of this requires a sandbox. It requires a function call.\n\nThe hidden cost is real:\n\n- A single AI query consumes **10x more energy** than a traditional search\n- Running workloads in Docker containers produces a [measurable increase in energy consumption](https://doi.org/10.1016/j.suscom.2023.100889) vs. bare Linux, due to I/O overhead\n- U.S. AI data centers are projected to emit **24-44 million metric tons of CO2/year by 2030** and consume water equivalent to **6-10 million Americans** ([Cornell, 2025](https://doi.org/10.1038/s44221-025-00410-9))\n\nBut when you *do* need isolation — running untrusted code, AI agents executing arbitrary commands, multi-tenant environments — you need it done right, and you need it done light.\n\nHiveBox is the proportionate answer: kernel-native isolation with near-zero overhead. No container runtime. No hypervisor. Just the Linux kernel doing what it already knows how to do.\n\n| | Docker | gVisor | Firecracker | Daytona | **HiveBox** |\n|---|---|---|---|---|---|\n| Memory per sandbox | ~50 MB | ~30 MB | ~5 MB | ~50 MB+ (Docker-based) | **~2-5 MB** |\n| Startup time | ~1 s | ~0.5 s | ~125 ms | ~90 ms (warm) | **~10-50 ms** |\n| Isolation | Namespaces | Syscall emulation | Hypervisor | Docker (managed) | **NS + seccomp + Landlock** |\n| Self-hosted | Yes | Yes | Yes | Yes (cloud also available, pay-per-second) | **Yes** |\n| Complexity | High | Medium | Medium | High (requires Docker Compose) | **Low** |\n\nSame security. A fraction of the resources. The smartest infrastructure is the one that uses the minimum needed for the task.\n\n## Deploy\n\nOne command on any Linux VPS (Ubuntu, Debian, etc.):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/TetiAI/hivebox/main/scripts/setup.sh | sudo bash\n```\n\nThis installs Docker (if needed), pulls the latest image, generates an API key, and starts HiveBox. The dashboard is available at `http://your-server:7070/dashboard`.\n\nTo pass custom configuration:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/TetiAI/hivebox/main/scripts/setup.sh | \\\n HIVEBOX_API_KEY=your-key \\\n HIVEBOX_OPENCODE_API_KEY=sk-... \\\n HIVEBOX_OPENCODE_MODEL=your-model \\\n HIVEBOX_PACKAGES=\"python3 nodejs git\" \\\n sudo -E bash\n```\n\n`HIVEBOX_PACKAGES` installs extra Debian packages into every sandbox at startup. All settings are saved in `/opt/hivebox/.env` and persist across restarts.\n\n## Quick Start\n\n### CLI\n\n```bash\n# Create a hivebox\nhivebox create --name myagent --memory 512m\n\n# Execute commands in it\nhivebox exec myagent -- echo \"hello from the hivebox\"\nhivebox exec myagent -- pip install requests numpy\nhivebox exec myagent -- python3 scraper.py\n\n# Check status\nhivebox list\n\n# Clean up\nhivebox destroy myagent\n```\n\n### REST API\n\n```bash\n# Start the daemon\nhivebox daemon --port 7070 --api-key mysecretkey\n\n# Create a hivebox\ncurl -X POST http://localhost:7070/api/v1/hiveboxes \\\n -H \"Authorization: Bearer mysecretkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"api-hivebox\", \"timeout\": 3600}'\n\n# Execute a command\ncurl -X POST http://localhost:7070/api/v1/hiveboxes/api-hivebox/exec \\\n -H \"Authorization: Bearer mysecretkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"command\": \"python3 -c \\\"print(1+1)\\\"\"}'\n\n# Destroy\ncurl -X DELETE http://localhost:7070/api/v1/hiveboxes/api-hivebox \\\n -H \"Authorization: Bearer mysecretkey\"\n```\n\n### MCP Bridge — Connect AI Agents to Sandboxes\n\nHiveBox includes a built-in MCP (Model Context Protocol) server that bridges any AI coding agent into a sandbox. No custom agent loop — just plug your favorite MCP-compatible client (OpenCode, Claude Code, etc.) into any hivebox.\n\n```\n[AI Client] --HTTP--> [hivebox daemon :7070/mcp] --nsenter--> [Sandbox]\n```\n\n**Setup:**\n\n1. Start the daemon and create a sandbox:\n```bash\nhivebox daemon --port 7070 --api-key mysecretkey\nhivebox create --name myworkspace --memory 512m\n```\n\n2. Configure your AI client to connect via MCP over HTTP (no local binary needed):\n```json\n{\n \"mcpServers\": {\n \"sandbox\": {\n \"url\": \"http://your-server:7070/api/v1/hiveboxes/{HIVEBOX_ID}/mcp\",\n \"headers\": { \"Authorization\": \"Bearer mysecretkey\" }\n }\n }\n}\n```\n\n3. The AI client now has 18 tools to operate inside the sandbox: `exec`, `read_file`, `read_multiple_files`, `write_file`, `edit_file`, `list_directory`, `directory_tree`, `search_files`, `glob`, `get_file_info`, `create_directory`, `move_file`, `upload_file`, `download_file`, `read_media_file`, `list_directory_with_sizes`, `list_skills`, `read_skill_file`.\n\n### OpenCode Agent — AI per Sandbox\n\nEach sandbox automatically gets its own [OpenCode](https://opencode.ai) AI agent, accessible through the same daemon port. No extra setup — create a sandbox and start chatting.\n\nOpenCode doesn't run *inside* the sandbox — it runs as a separate `opencode serve` process on the host, connected to the hivebox via MCP. The daemon proxies all requests through port 7070, so each sandbox's agent is accessible at `/api/v1/hiveboxes/{id}/opencode/` without exposing internal ports.\n\n```bash\n# Create a sandbox (opencode starts automatically)\ncurl -X POST http://localhost:7070/api/v1/hiveboxes \\\n -H \"Authorization: Bearer mysecretkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"my-agent\"}'\n\n# Connect to the real-time event stream (SSE)\ncurl -N http://localhost:7070/api/v1/hiveboxes/my-agent/opencode/event \\\n -H \"Authorization: Bearer mysecretkey\"\n\n# Create a session\ncurl -X POST http://localhost:7070/api/v1/hiveboxes/my-agent/opencode/session \\\n -H \"Authorization: Bearer mysecretkey\" \\\n -H \"Content-Type: application/json\" -d '{}'\n\n# Send a prompt (response streams via SSE)\ncurl -X POST http://localhost:7070/api/v1/hiveboxes/my-agent/opencode/session/{SESSION_ID}/prompt_async \\\n -H \"Authorization: Bearer mysecretkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"parts\":[{\"type\":\"text\",\"text\":\"create a hello world script\"}]}'\n```\n\nOpenCode is enabled by default. Disable it with `HIVEBOX_OPENCODE=false`.\n\n### Skills — Domain Expertise for the Agent\n\nEach hivebox agent has access to a library of specialized skills (PDF, PPTX, DOCX, XLSX, and more). Skills are served directly by the hivebox MCP via two tools:\n\n- **`list_skills`** — lists available skills with their descriptions\n- **`read_skill_file`** — reads any file from a skill directory (SKILL.md for instructions, reference files for library docs)\n\nThe agent follows a progressive disclosure pattern:\n1. Calls `list_skills` to discover what's available\n2. Calls `read_skill_file` to load a skill's instructions\n3. Reads any referenced support files (e.g. `pptxgenjs.md`, `forms.md`)\n4. Executes the skill's scripts via `exec`\n\nSkills are stored in `/opt/hivebox/skills/` (inside the container). Anthropic's pre-built skills are included by default. To add custom skills:\n\n```bash\n# At runtime — mount a skill directory\ndocker run ... -v /path/to/my-skill:/opt/hivebox/skills/my-skill:ro hivebox\n\n# At build time — add a folder to skills/ in this repo\n```\n\n### Web Dashboard\n\nHiveBox includes a built-in web dashboard for managing hiveboxes from the browser.\nStart the daemon and navigate to:\n\n```\nhttp://localhost:7070/dashboard\n```\n\nThe dashboard provides:\n- Login with API key\n- Create, list, and destroy hiveboxes\n- Built-in terminal to execute commands in any hivebox\n- **Agent playground** with real-time SSE streaming for each hivebox\n- Real-time hivebox status (uptime, TTL, resource usage, command count)\n- Auto-refresh every 5 seconds\n\nNo external dependencies — everything is embedded in the binary.\n\n## Architecture\n\nHiveBox uses three components:\n\n1. **Linux host** — any Linux with kernel 5.15+ (Debian, Ubuntu, etc.)\n2. **`hivebox` binary** — single static Rust binary (~5 MB) managing hivebox lifecycle\n3. **Rootfs image** — Debian base squashfs image mounted with overlayfs\n\n### Six Layers of Isolation\n\nEvery hivebox is protected by six independent security layers:\n\n```\n+---------------------------------------------------+\n| User Command |\n+---------------------------------------------------+\n| 6. seccomp-BPF — syscall allow-list |\n| 5. Capabilities — minimal privilege set |\n| 4. Landlock LSM — filesystem path control |\n| 3. pivot_root — filesystem isolation |\n| 2. cgroup v2 — resource limits |\n| 1. Namespaces — process/net/mount/user |\n+---------------------------------------------------+\n| Linux Kernel |\n+---------------------------------------------------+\n```\n\n1. **Namespaces** (PID, Mount, Network, User, UTS, IPC) — complete process isolation\n2. **cgroup v2** — memory, CPU, PID limits; swap disabled\n3. **pivot_root** — host filesystem becomes unreachable\n4. **Landlock LSM** — path-based filesystem access control\n5. **Capability dropping** — minimal privilege set + `NO_NEW_PRIVS`\n6. **seccomp-BPF** — syscall allow-list (~80 default, ~40 strict)\n\n### Filesystem\n\nEach hivebox uses overlayfs over squashfs base images:\n\n```\nmerged/ (rw) <- hivebox sees this\n +-- upper/ (tmpfs) <- writes go here (vanishes on destroy)\n +-- squashfs/ (ro) <- shared Debian base across all hiveboxes\n```\n\n### Networking\n\nThree modes: `none` (default, no network), `isolated` (NAT to internet), `shared` (bridge between hiveboxes).\n\n## Building\n\nRequires Rust toolchain. Target platform: Linux with kernel 5.15+.\n\n```bash\n# Development build\ncargo build\n\n# Static release build (musl, runs on any Linux)\ncargo build --release --target x86_64-unknown-linux-musl\n\n# The binary is fully static — copy it anywhere\ncp target/x86_64-unknown-linux-musl/release/hivebox /usr/bin/\n```\n\n### Docker\n\n```bash\n# Build the image\ndocker build -t hivebox .\n\n# Run with privileged mode and host cgroup namespace\ndocker run --privileged --cgroupns=host -p 7070:7070 \\\n -e HIVEBOX_API_KEY=your-secret-key \\\n -e HIVEBOX_PACKAGES=\"python3 nodejs git\" \\\n hivebox\n```\n\n**Environment variables:**\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HIVEBOX_API_KEY` | API key for authentication (`Authorization: Bearer `) | *(none — auth disabled)* |\n| `HIVEBOX_OPENCODE` | Enable OpenCode agent per sandbox (`true`/`false`) | `true` |\n| `HIVEBOX_OPENCODE_BASE_URL` | Default LLM base URL for all sandboxes | *(opencode default)* |\n| `HIVEBOX_OPENCODE_API_KEY` | Default LLM API key for all sandboxes | *(opencode default)* |\n| `HIVEBOX_OPENCODE_MODEL` | Default LLM model for all sandboxes | *(opencode default)* |\n| `HIVEBOX_OPENCODE_SKILLS_PATH` | Path to skills directory | `/opt/hivebox/skills` |\n| `HIVEBOX_OPENCODE_MCPS` | JSON of global MCP servers added to every sandbox | *(none)* |\n| `HIVEBOX_PACKAGES` | Debian packages to install at startup (also reported to agents as pre-installed) | *(none)* |\n| `HIVEBOX_PIP_PACKAGES` | pip packages to install at startup (also reported to agents as pre-installed) | *(none)* |\n| `HIVEBOX_NPM_PACKAGES` | npm global packages to install at startup (also reported to agents as pre-installed) | *(none)* |\n\nAll LLM and MCP settings can be overridden per-sandbox at creation time via the API (see [API docs](docs/api.md)).\n\n> **Note**: `--privileged` is required for Linux namespaces, cgroups, and mount operations.\n> `--cgroupns=host` gives access to the host cgroup hierarchy, needed for memory/CPU/PID limits on hiveboxes. Without it, hiveboxes still work but without resource limits.\n\n## Deployment\n\n### Build rootfs image\n\n```bash\nsudo bash scripts/build-images.sh\n```\n\nThis builds the Debian base squashfs image. To pre-install packages in all hiveboxes, add them to the Dockerfile or the base image build script. For per-hivebox packages, use `hivebox exec -- apt-get install `.\n\n### Start the daemon\n\n```bash\n# Direct\nhivebox daemon --port 7070 --api-key your-secret-key\n\n# OpenRC\nsudo cp config/hivebox.openrc /etc/init.d/hivebox\nsudo rc-update add hivebox default\nsudo rc-service hivebox start\n```\n\nSee [docs/deployment.md](docs/deployment.md) for full production setup.\n\n## API Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/healthz` | Health check (no auth) |\n| `POST` | `/api/v1/hiveboxes` | Create hivebox |\n| `GET` | `/api/v1/hiveboxes` | List hiveboxes |\n| `GET` | `/api/v1/hiveboxes/:id` | Get hivebox details |\n| `POST` | `/api/v1/hiveboxes/:id/exec` | Execute command |\n| `POST` | `/api/v1/hiveboxes/:id/mcp` | MCP over HTTP |\n| `PUT` | `/api/v1/hiveboxes/:id/files` | Upload file |\n| `GET` | `/api/v1/hiveboxes/:id/files` | Download file |\n| `DELETE` | `/api/v1/hiveboxes/:id` | Destroy hivebox |\n| `GET` | `/api/v1/analytics` | Metrics history |\n| `ANY` | `/api/v1/hiveboxes/:id/opencode/*` | OpenCode agent proxy |\n\nSee [docs/api.md](docs/api.md) for full API reference.\n\n## Documentation\n\n- [Architecture](docs/architecture.md) — design, filesystem layout, networking\n- [API Reference](docs/api.md) — REST API endpoints and examples\n- [CLI Reference](docs/cli.md) — all commands and flags\n- [Deployment Guide](docs/deployment.md) — production setup, OpenRC, systemd\n- [Security Model](docs/security.md) — threat model, security layers, limitations\n\n## Disclaimer\n\nHiveBox is **experimental software** under active development. It is **not production-ready** and should not be used in critical or production environments. The authors assume no responsibility for any damage, data loss, or security issues that may arise from its use. Use at your own risk.\n\n## License\n\nBSD 3 — see [LICENSE](LICENSE).\n"}