boxed

README

Boxed

A self-hosted code execution substrate for AI agents. Ephemeral Docker sandboxes with a streaming in-sandbox agent, behind a driver interface designed to admit other isolation backends.

---

The Story 📖

Building an AI Agent that writes code? You have a problem.

• Run it locally? 🚨 Security Risk. One rm -rf / and your laptop is gone.
• Run it in cloud? 💸 Expensive. AWS instances for every user?
• Use SaaS sandbox? 🐌 Vendor Lock-in. High latency and data privacy concerns.

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.

---

✨ Features

• 🔒 Backend behind an interface — one Driver interface; the Docker driver is the only implementation. Set BOXED_DOCKER_RUNTIME=runsc (gVisor) or =kata to swap the OCI runtime under it; the paper measures all three on one host. No Firecracker or Wasm driver exists yet.
• 🛡️ Bring-Your-Own-Key auth — operator-chosen API key via X-Boxed-API-Key. No vendor accounts.
• ⚡ Fast lifecycle — create+exec+destroy measured against raw Docker on the same host; numbers and CIs in the paper and bench/results/.
• 📁 First-class artifacts — in-VM Rust agent streams stdout, stderr, and emitted files (images, PDFs, datasets) over JSON-RPC.
• 🔌 Polyglot SDKs — first-class support for TypeScript and Python.
• 🌐 Network fail-closed — every sandbox runs with Docker's none network; requests that enable networking are rejected until a per-sandbox egress policy exists.

Scoping: the Docker driver sets a read-only root filesystem, CapDrop: ALL, no-new-privileges, PidsLimit 256, a memory cgroup (default 512 MiB), a CPU quota, tmpfs for /tmp, /output, and the workdir, and network none. It uses Docker's default seccomp profile; a custom profile and a per-sandbox egress policy are not implemented. A twelve-vector escape probe with post-condition checks (bench/security/escapes.sh) and its results are in the paper and bench/results/. Docker shares the host kernel: this is configuration hardening, not a virtualization boundary.

---

🚀 Getting Started

📋 Prerequisites

To run Boxed locally, you'll need:

• Go 1.22+ (for the Control Plane)
• Rust 1.75+ (for the Agent)
• Docker Desktop (running and accessible)
• Standard Images: Ensure you have a base image like python:3.10-slim pulled:

  docker pull python:3.10-slim
  

[!NOTE] First Run: The first sandbox creation may take a few seconds while Docker pulls the required images. Subsequent runs are near-instant.

---

🏗️ Local Development

We provide a Makefile to simplify the build process.

# 1. Clone the repository
git clone https://github.com/akshayaggarwal99/boxed.git
cd boxed

# 2. Build everything (Agent + CLI)
make build

# 3. Start the Control Plane with Auth
export BOXED_API_KEY="super-secret-key"
./bin/boxed serve --api-key $BOXED_API_KEY

# Cleanup build artifacts
make clean

🔐 Security & Auth

Boxed uses a Bring Your Own Key (BYOK) model. Since you run your own instance, you define the secret key yourself at startup.

You can set the key via the --api-key flag or BOXED_API_KEY environment variable:

All CLI commands and SDKs must provide this key:

./bin/boxed list --api-key $BOXED_API_KEY

---

💻 CLI Usage

# Run interactive REPL (Sticky Session)
./bin/boxed repl <sandbox-id> --lang python

---

🔌 SDKs

TypeScript

# Local install
npm install ./sdk/typescript

Python

# Local install
pip install -e ./sdk/python

---

💻 SDK Examples

Python

from boxed_sdk import Boxed

client = Boxed(base_url="http://localhost:8080", api_key="super-secret-key")

# Create a secure session
session = client.create_session(template="python:3.10-slim")

# Run unsafe code
result = session.run("print('hello from boxed')")
print(result.stdout)

# Cleanup
session.close()

---

📚 Documentation

• REST API Reference — Detailed specification of all endpoints.
• OpenAPI Spec — Raw OpenAPI 3.0 definition.

---

📄 Paper

A preprint describing Boxed's design and an open benchmark harness is available in this repo:

• PDF: paper-v2/Boxed-IEEE.pdf — IEEE conference format, 9 pages
• Source: paper-v2/main.tex (cd paper-v2 && make, needs tectonic)
• Benchmark harness (reproducible): bench/
• Raw experiment data: bench/results/*.csv

Every performance number in the paper expands from a LaTeX macro in paper-v2/tables/numbers.tex, which is generated by bench/analyze/stats.py from those CSVs — the prose cannot drift from the data.

paper/ holds the superseded v1 draft. It states that the in-sandbox agent runs as PID 1 and that large artifacts are handed back via a pre-signed URL; neither is true of the implementation. Both are corrected in v2. Read v2.

Headline numbers (MacBook Pro M1 Pro, 16 GB, macOS, Docker Desktop; n=200 cold-start trials):

Metric	Value
Median create+exec+destroy	303 ms
p95 / p99	395 ms / 495 ms
Peak throughput	9.8 sandboxes/s
Idle agent RSS (median)	0.4 MiB
Behavioural escape probe	5/12 denied
HumanEval-style agent trace	20/20 passed

To reproduce:

cd bench && make all   # requires `boxed serve` running and BOXED_API_KEY set

Cite

@misc{boxed2026,
  title  = {Boxed: A Sovereign, Polyglot Sandbox Substrate for Autonomous Code-Generating Agents},
  author = {Kumar, Akshay},
  year   = {2026},
  howpublished = {\url{https://github.com/akshayaggarwal99/boxed/blob/main/paper-v2/Boxed-IEEE.pdf}}
}

---

🛠️ Architecture

Boxed uses a Control Plane vs Data Plane architecture.

• Control Plane (Go): REST API + WebSocket gateway with BYOK API-key auth (Echo, ~2.8k LOC, 12 MiB binary).
• Agent (Rust): Lightweight 1.32 MiB stripped binary injected into every sandbox; streams stdout/stderr/artifacts over JSON-RPC.

---

🗺️ Roadmap

• Docker driver + Go control plane + Rust in-VM agent
• Polyglot SDKs (TypeScript, Python)
• Sticky sessions (REPL mode, WebSocket proxy)
• API-key auth (Bring-Your-Own-Key)
• Hardening — ReadonlyRootfs, CapDrop: ALL, no-new-privileges, PidsLimit, network none
• Custom seccomp profile and fine-grained egress allow-lists
• Firecracker driver — MicroVMs for stronger isolation
• Wasm driver — sub-millisecond cold start for compatible workloads
• Pool-based reuse — warm sandboxes for sub-millisecond exec (see paper §6)
• Multi-host scheduler

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

📄 License

MIT License — do whatever you want with it.