{"id":49026130,"url":"https://github.com/akshayaggarwal99/boxed","last_synced_at":"2026-06-09T10:01:17.475Z","repository":{"id":355788619,"uuid":"1127147572","full_name":"akshayaggarwal99/boxed","owner":"akshayaggarwal99","description":"The Sovereign Code Execution Engine for AI Agents. Run untrusted code safely locally or in the cloud using Docker, Firecracker, or Wasm.","archived":false,"fork":false,"pushed_at":"2026-01-05T17:27:17.000Z","size":150,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-05T10:05:01.529Z","etag":null,"topics":["ai-agent","ai-agents","environment","safe","sandbox","secure-runtime","vercel-sandbox","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akshayaggarwal99.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-01-03T09:26:38.000Z","updated_at":"2026-04-20T15:14:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akshayaggarwal99/boxed","commit_stats":null,"previous_names":["akshayaggarwal99/boxed"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/akshayaggarwal99/boxed","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshayaggarwal99%2Fboxed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshayaggarwal99%2Fboxed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshayaggarwal99%2Fboxed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshayaggarwal99%2Fboxed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akshayaggarwal99","download_url":"https://codeload.github.com/akshayaggarwal99/boxed/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshayaggarwal99%2Fboxed/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34101070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agent","ai-agents","environment","safe","sandbox","secure-runtime","vercel-sandbox","virtualization"],"created_at":"2026-04-19T07:00:20.155Z","updated_at":"2026-06-09T10:01:17.470Z","avatar_url":"https://github.com/akshayaggarwal99.png","language":"Go","funding_links":[],"categories":["Virtual machines and microVM platforms"],"sub_categories":["Multiplatform"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Boxed Logo\" width=\"320\"\u003e\n\u003c/p\u003e\n\n# Boxed\n\n**The Sovereign Code Execution Engine for AI Agents. Run untrusted code safely—locally or in the cloud—using Docker, Firecracker, or Wasm.**\n\n[![Go](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go)](https://go.dev)\n[![Rust](https://img.shields.io/badge/Rust-1.75+-DEA584?logo=rust)](https://www.rust-lang.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-SDK-3178C6?logo=typescript)](https://www.typescriptlang.org/)\n[![Python](https://img.shields.io/badge/Python-SDK-3776AB?logo=python)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n---\n\n## The Story 📖\n\nBuilding an AI Agent that writes code? You have a problem.\n\n*   Run it locally? 🚨 **Security Risk.** One `rm -rf /` and your laptop is gone.\n*   Run it in cloud? 💸 **Expensive.** AWS instances for every user?\n*   Use SaaS sandbox? 🐌 **Vendor Lock-in.** High latency and data privacy concerns.\n\n**Meet Boxed.** The open-source, sovereign engine that gives your Agents a safe place to play. It provides a unified API to spawn ephemeral sandboxes, execute arbitrary code, and retrieve results instantly.\n\n---\n\n## ✨ Features\n\n- **🔒 Pluggable isolation** — Docker driver ships today; Firecracker and Wasm drivers stubbed behind a single `Driver` interface.\n- **🛡️ Bring-Your-Own-Key auth** — operator-chosen API key via `X-Boxed-API-Key`. No vendor accounts.\n- **⚡ Sub-second cold start** — 303 ms median create+exec+destroy on a developer laptop (see paper).\n- **📁 First-class artifacts** — in-VM Rust agent streams stdout, stderr, and emitted files (images, PDFs, datasets) over JSON-RPC.\n- **🔌 Polyglot SDKs** — first-class support for TypeScript and Python.\n- **🌐 Network policy** — coarse `EnableNetworking` toggle today (Docker `none` vs bridge); fine-grained egress allow-lists are on the roadmap.\n\n\u003e **Honest scoping:** the current Docker driver enforces a `Memory` cgroup (default 512 MiB) and runs `/tmp` and `/output` as `tmpfs`, but leaves the container rootfs writable, retains the default Linux capability set (no `CapDrop: ALL`), does not set `PidsLimit`, and permits in-PID-namespace `ptrace`. We report the full escape probe in the [paper](paper/main.pdf) and close those gaps in the planned Firecracker driver.\n\n---\n\n## 🚀 Getting Started\n\n### 📋 Prerequisites\n\nTo run Boxed locally, you'll need:\n- **Go 1.22+** (for the Control Plane)\n- **Rust 1.75+** (for the Agent)\n- **Docker Desktop** (running and accessible)\n- **Standard Images**: Ensure you have a base image like `python:3.10-slim` pulled:\n  ```bash\n  docker pull python:3.10-slim\n  ```\n\u003e [!NOTE]\n\u003e **First Run**: The first sandbox creation may take a few seconds while Docker pulls the required images. Subsequent runs are near-instant.\n\n---\n\n### 🏗️ Local Development\n\nWe provide a `Makefile` to simplify the build process.\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/akshayaggarwal99/boxed.git\ncd boxed\n\n# 2. Build everything (Agent + CLI)\nmake build\n\n# 3. Start the Control Plane with Auth\nexport BOXED_API_KEY=\"super-secret-key\"\n./bin/boxed serve --api-key $BOXED_API_KEY\n\n# Cleanup build artifacts\nmake clean\n```\n\n### 🔐 Security \u0026 Auth\n\nBoxed uses a **Bring Your Own Key (BYOK)** model. Since you run your own instance, you define the secret key yourself at startup. \n\nYou can set the key via the `--api-key` flag or `BOXED_API_KEY` environment variable:\n\nAll CLI commands and SDKs must provide this key:\n```bash\n./bin/boxed list --api-key $BOXED_API_KEY\n```\n\n---\n\n### 💻 CLI Usage\n\n```bash\n# Run interactive REPL (Sticky Session)\n./bin/boxed repl \u003csandbox-id\u003e --lang python\n```\n\n---\n\n### 🔌 SDKs\n\n#### TypeScript\n```bash\n# Local install\nnpm install ./sdk/typescript\n```\n\n#### Python\n```bash\n# Local install\npip install -e ./sdk/python\n```\n\n---\n\n### 💻 SDK Examples\n\n#### Python\n```python\nfrom boxed_sdk import Boxed\n\nclient = Boxed(base_url=\"http://localhost:8080\", api_key=\"super-secret-key\")\n\n# Create a secure session\nsession = client.create_session(template=\"python:3.10-slim\")\n\n# Run unsafe code\nresult = session.run(\"print('hello from boxed')\")\nprint(result.stdout)\n\n# Cleanup\nsession.close()\n```\n\n---\n\n## 📚 Documentation\n\n- **[REST API Reference](docs/api.md)** — Detailed specification of all endpoints.\n- **[OpenAPI Spec](api/openapi.yaml)** — Raw OpenAPI 3.0 definition.\n\n---\n\n## 📄 Paper\n\nA preprint describing Boxed's design and an open benchmark harness is available in this repo:\n\n- **PDF:** [`paper/main.pdf`](paper/main.pdf)\n- **Source:** [`paper/main.tex`](paper/main.tex)\n- **Benchmark harness (reproducible):** [`bench/`](bench/)\n- **Raw experiment data:** [`bench/results/*.csv`](bench/results/)\n\nHeadline numbers (MacBook Pro M1 Pro, 16 GB, macOS, Docker Desktop; n=200 cold-start trials):\n\n| Metric                         | Value             |\n|--------------------------------|-------------------|\n| Median create+exec+destroy     | **303 ms**        |\n| p95 / p99                      | 395 ms / 495 ms   |\n| Peak throughput                | 9.8 sandboxes/s   |\n| Idle agent RSS (median)        | 0.4 MiB           |\n| Behavioural escape probe       | 5/12 denied       |\n| HumanEval-style agent trace    | 20/20 passed      |\n\nTo reproduce:\n\n```bash\ncd bench \u0026\u0026 make all   # requires `boxed serve` running and BOXED_API_KEY set\n```\n\n### Cite\n\n```bibtex\n@misc{boxed2026,\n  title  = {Boxed: A Sovereign, Polyglot Sandbox Substrate for Autonomous Code-Generating Agents},\n  author = {Kumar, Akshay},\n  year   = {2026},\n  howpublished = {\\url{https://github.com/akshayaggarwal99/boxed/blob/main/paper/main.pdf}}\n}\n```\n\n---\n\n## 🛠️ Architecture\n\nBoxed uses a **Control Plane vs Data Plane** architecture.\n\n![Architecture Diagram](architecture.svg)\n\n*   **Control Plane (Go)**: REST API + WebSocket gateway with BYOK API-key auth (Echo, ~2.8k LOC, 12 MiB binary).\n*   **Agent (Rust)**: Lightweight 1.32 MiB stripped binary injected into every sandbox; streams stdout/stderr/artifacts over JSON-RPC.\n\n---\n\n## 🗺️ Roadmap\n\n- [x] **Docker driver** + Go control plane + Rust in-VM agent\n- [x] **Polyglot SDKs** (TypeScript, Python)\n- [x] **Sticky sessions** (REPL mode, WebSocket proxy)\n- [x] **API-key auth** (Bring-Your-Own-Key)\n- [ ] **Hardening** — `ReadonlyRootfs`, `CapDrop: ALL`, `PidsLimit`, tighter seccomp profile, fine-grained egress allow-lists via `iptables`\n- [ ] **Firecracker driver** — MicroVMs for stronger isolation\n- [ ] **Wasm driver** — sub-millisecond cold start for compatible workloads\n- [ ] **Pool-based reuse** — warm sandboxes for sub-millisecond `exec` (see paper §6)\n- [ ] **Multi-host scheduler**\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).\n\n## 📄 License\n\nMIT License — do whatever you want with it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshayaggarwal99%2Fboxed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakshayaggarwal99%2Fboxed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshayaggarwal99%2Fboxed/lists"}