vivek1504/agent-sandbox

---

Overview

AI agents need to perform real-world actions: generate and execute code, install third-party dependencies, query remote APIs, run background processes, and manipulate files. Running untrusted, agent-generated code on the host machine is dangerous, while conventional container sandboxing shares the host kernel—leaving systems vulnerable to kernel exploits, dirty sysctls, and resource exhaustion.

Agent Sandbox provides each AI agent session with a dedicated Firecracker microVM. Sessions boot in milliseconds from pre-baked snapshots, run in complete hardware isolation with their own Linux kernel, and are automatically torn down when execution completes.

[!NOTE] Sub-100ms Cold Starts: By combining Firecracker snapshot restoration with pre-provisioned root filesystems, microVM guest state restores in ~2.6ms (total end-to-end cold start is ~90ms including dedicated Linux network namespace, veth pair, TAP device, and NAT egress provisioning).

---

Architecture

Agent Sandbox separates untrusted guest execution from the host control plane through strict virtualization and network boundaries.

Execution Flow

1. Session Request: An agent issues a command through the TypeScript SDK, MCP protocol, or REST API, specifying an optional template (node, python, go).
2. Snapshot Lookup: The Session Gateway checks for an active instance. If cold, it fetches pre-baked snapshot state from the Template Registry and restores the microVM in ~2.6ms.
3. Network Isolation: The host configures a dedicated Linux network namespace with an isolated veth pair, TAP device, custom routing table, and iptables rules.
4. Vsock Dispatch: Commands and payloads stream directly to the guest runtime over a zero-network vsock channel.
5. Reaping & Teardown: Inactive sessions are automatically reaped after an idle timeout (default: 30 minutes), removing the jail chroot, network namespace, and cgroup slices.

Network Packet Path & Isolation Boundary

MicroVM Guest (eth0: 192.168.241.2/29)
    ↓
tap0 (192.168.241.1/29) — Inside Per-VM Network Namespace
    ↓
Per-Namespace iptables:
  ├── PREROUTING: Transparent DNS redirection (UDP/TCP 53 → local dnsmasq)
  ├── FORWARD → VM_EGRESS: Cloud metadata block (169.254.169.254/32) + optional CIDR rules
  └── POSTROUTING: MASQUERADE 192.168.241.0/29 outbound to vethNs
    ↓
vethNs (10.0.{slot}.1/30)
    ↓ (veth pair across network namespace boundary)
vethHost (10.0.{slot}.2/30) — On Host
    ↓
Host-Level iptables:
  ├── INPUT: DROP all incoming traffic from 10.0.0.0/16 to host daemon ports
  ├── FORWARD: DROP 169.254.169.254/32 (Defense-in-depth metadata blocking)
  ├── FORWARD: DROP 10.0.0.0/16 → 10.0.0.0/16 (Strict cross-tenant VM isolation)
  ├── FORWARD: ACCEPT 10.0.0.0/16 outbound & return conntrack
  └── POSTROUTING: MASQUERADE 10.0.0.0/16 outbound to physical WAN interface
    ↓
Internet

---

Capabilities

Environment Templates

Agent Sandbox comes with three pre-configured templates:

• node (Default): Alpine Linux 3.20 + Node.js 22 + npm + git + curl
• python: Alpine Linux 3.20 + Python 3.12 + pip + git + curl
• go: Alpine Linux 3.20 + Go 1.23 + git + curl

Building & Creating Custom Templates

Build any bundled or custom template using the snapshot script:

# Build bundled templates
sudo ./templates/build.sh node
sudo ./templates/build.sh python
sudo ./templates/build.sh go

To create a custom environment, create a directory under templates// with a Dockerfile:

FROM agent-sandbox-base:latest

RUN apk add --no-cache ruby rust cargo postgresql-client

LABEL template.name="data-science" \
      template.displayName="Data Science & Rust" \
      template.tools="ruby,rustc,cargo,psql"

Build the snapshot:

sudo ./templates/build.sh data-science

---

Getting Started

Prerequisites

• Linux Host with hardware virtualization enabled (/dev/kvm must exist and be accessible)
• Firecracker & Jailer v1.16+ installed in /usr/local/bin/
• Node.js v20+
• Docker (used solely during template build pipeline)
• Root / sudo privileges (required for Jailer chroot, cgroups, and network namespaces)

[!IMPORTANT] Agent Sandbox requires Linux KVM acceleration. It cannot run inside standard non-nested containers or on macOS/Windows hosts without nested virtualization support.

1. Install Firecracker & Jailer

Download the binaries from the official Firecracker releases:

ARCH="$(uname -m)"
RELEASE_URL="https://github.com/firecracker-microvm/firecracker/releases"
LATEST=$(basename $(curl -fsSLI -o /dev/null -w %{url_effective} ${RELEASE_URL}/latest))

curl -L "${RELEASE_URL}/download/${LATEST}/firecracker-${LATEST}-${ARCH}.tgz" | tar -xz

sudo mv "release-${LATEST}-${ARCH}/firecracker-${LATEST}-${ARCH}" /usr/local/bin/firecracker
sudo mv "release-${LATEST}-${ARCH}/jailer-${LATEST}-${ARCH}" /usr/local/bin/jailer
rm -rf "release-${LATEST}-${ARCH}"

2. Configure System User & IP Forwarding

The Jailer drops privileges to a dedicated unprivileged user (firecracker):

# Create firecracker system user and group
sudo groupadd -g 982 firecracker 2>/dev/null || true
sudo useradd -u 997 -g 982 -M -s /usr/sbin/nologin firecracker 2>/dev/null || true

# Enable IPv4 forwarding for guest internet access
sudo sysctl -w net.ipv4.ip_forward=1
echo "net.ipv4.ip_forward = 1" | sudo tee /etc/sysctl.d/99-ip-forward.conf

3. Install Project Dependencies & Kernel Artifact

git clone https://github.com/vivek1504/agent-sandbox.git
cd agent-sandbox
npm install

# Setup artifacts directory and download kernel
sudo mkdir -p /var/lib/agent-sandbox/artifacts
wget https://github.com/vivek1504/agent-sandbox/releases/download/Beta/vmlinux
sudo mv vmlinux /var/lib/agent-sandbox/artifacts/
sudo chown -R root:firecracker /var/lib/agent-sandbox/artifacts
sudo chmod 750 /var/lib/agent-sandbox/artifacts

4. Build Templates & Start the Server

# Build base Node.js template snapshot
sudo ./templates/build.sh node

# Start the server (requires root for Jailer and netns configuration)
sudo npm start
# Server listening on http://localhost:3000

5. Verify Installation

# Health probe
curl http://localhost:3000/health

# Execute a command in a fresh microVM
curl -X POST http://localhost:3000/exec/test-session/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "node", "args": ["-e", "console.log(process.version)"]}'

---

Integration & SDKs

Agent Sandbox offers three integration surfaces: a typed TypeScript/JavaScript SDK, a Model Context Protocol (MCP) server for autonomous agents, and a direct REST API.

TypeScript / JavaScript SDK

The official client SDK (@agent-sandbox/sdk) is zero-dependency and runs across Node.js 18+, Bun, and Deno.

npm install ./sdk/typescript

import { Sandbox } from "@agent-sandbox/sdk";

const sandbox = new Sandbox({
  baseUrl: "http://localhost:3000",
  headers: { Authorization: "Bearer sk_test_..." },
});

// Create a session backed by Python
const session = sandbox.create({ template: "python" });

// Run code directly
const result = await session.runCode("print('Hello from isolated microVM!')");
console.log(result.output[0].data);

// Stream command output in real time
for await (const chunk of session.execStream("pip", { args: ["install", "requests"] })) {
  if (chunk.type === "stream") process.stdout.write(chunk.data!);
}

// Write and read files inside the session workspace
await session.writeFile("script.py", 'print("File execution works")');
const { content } = await session.readFile("script.py");

// Destroy the session and reclaim microVM resources
await session.destroy();

Model Context Protocol (MCP)

Connect Claude Desktop, Cursor, or custom MCP-compatible AI agents directly to Agent Sandbox.

Stdio Configuration

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "node",
      "args": ["/path/to/agent-sandbox/dist/mcp/stdio.js"],
      "env": {
        "FIRECRACKER_JAIL_BASE": "/var/lib/agent-sandbox/jailer",
        "FIRECRACKER_ARTIFACTS_DIR": "/var/lib/agent-sandbox/artifacts"
      }
    }
  }
}

MCP Tools Reference

REST API

The HTTP server exposes JSON endpoints under /exec:

# List available environment templates
curl -H "Authorization: Bearer sk_test_..." http://localhost:3000/exec/templates

# Execute command (buffered JSON response)
curl -X POST http://localhost:3000/exec/session-1/execute \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"template": "node", "command": "node", "args": ["-e", "console.log(1+1)"]}'

# Execute command with streaming NDJSON output
curl -X POST http://localhost:3000/exec/session-1/execute \
  -H "Authorization: Bearer sk_test_..." \
  -H "Accept: application/x-ndjson" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm", "args": ["install", "express"]}'

# Write a file to /workspace
curl -X POST http://localhost:3000/exec/session-1/write \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"path": "hello.txt", "content": "Hello World"}'

# Read a file from /workspace
curl -H "Authorization: Bearer sk_test_..." \
  "http://localhost:3000/exec/session-1/read?path=hello.txt"

# List files in /workspace
curl -H "Authorization: Bearer sk_test_..." \
  "http://localhost:3000/exec/session-1/files?recursive=true"

# Terminate session
curl -X DELETE -H "Authorization: Bearer sk_test_..." \
  http://localhost:3000/exec/session-1

Authentication & API Key Management

Agent Sandbox includes a built-in scoped API key manager with per-key rate limiting.

[!NOTE] In accordance with OWASP security practices, API keys are accepted exclusively via HTTP headers (Authorization: Bearer or X-API-Key: ). Query-string authentication is rejected to prevent credentials leaking into access logs.

Manage keys via the CLI:

# Generate a key with 'exec' scope
npm run keys create "agent-key"

# Generate an admin key with rate limiting (100 req/min)
npm run keys create "admin-key" --scopes exec,admin,metrics --rate-limit 100

# List, rotate, or revoke keys
npm run keys list
npm run keys rotate 
npm run keys revoke 

---

Security Model

Agent Sandbox employs defense-in-depth isolation across compute, process, filesystem, and network layers:

Threat Mitigations

---

Performance & Benchmarks

An automated microsecond-accurate benchmark harness (npm run bench) profiles end-to-end performance across all subsystems.

• Test System: Ubuntu 24.04 LTS (Linux 6.17), Intel Core i5-11400H @ 2.70GHz, 6 Cores / 12 Threads, 8GB RAM, KVM enabled.

1. VM Lifecycle (Cold Start)

[!TIP] Restoring the Firecracker microVM snapshot takes only ~2.6ms. Over 60% of cold-start latency is dedicated to provisioning the isolated Linux network namespace (~55ms).

2. Concurrency Scaling

3. Cleanup & Teardown Latency

---

Configuration

Configure Agent Sandbox through environment variables (or an .env file):

---

Observability

Agent Sandbox includes production-grade observability out of the box:

• Prometheus Metrics (GET /metrics): Tracks active_vm_count, vm_creation_time, exec_sessions_active, exec_session_duration_seconds, exec_message_duration_seconds, vsock_connection_time, and egress policies.
• Liveness & Readiness Probes:
  • GET /health — Verifies process uptime.
  • GET /ready — Evaluates node readiness and host memory headroom.

---

Testing & Benchmarks

# Run unit & integration test suites (Vitest)
npm test

# Run Firecracker microVM end-to-end integration test (requires KVM + root)
sudo npm run test:e2e

# Run test suite with coverage report
npm run test:coverage

# Run microsecond benchmark harness
sudo npm run bench

# Run specific benchmark suite (e.g. lifecycle with 20 iterations)
sudo npm run bench -- -s vm -i 20