Agent Sandbox

Overview

An isolated execution environment for AI agents built with Firecracker microVMs. Provides hardware-level isolation, millisecond snapshot restore, and full Linux environments with pre-built Node.js, Python, and Go templates for safe code execution.

Agent Sandbox provides hardware-isolated execution environments for AI agents using Firecracker microVMs. Each session gets a dedicated Linux kernel, filesystem, and network stack, with pre-snapshotted templates that restore in milliseconds. The platform supports REST API, MCP protocol, and TypeScript SDK integration.

Key Features

Technology Stack

Challenges

• Achieving sub-100ms cold start while maintaining full hardware isolation

• Building secure network isolation without compromising outbound connectivity

• Creating a unified protocol for host-to-guest communication over vsock

• Preventing resource exhaustion from malicious or runaway agent code

• Supporting multiple language runtimes without bloating the base image

Solutions

• Implemented Firecracker snapshot/restore for ~2.6ms VM boot time

• Built per-VM network namespaces with veth pairs, TAP devices, and iptables NAT

• Designed vsock-based IPC protocol with JSON-RPC message framing

• Applied cgroup limits (CPU quota, memory max, pids.max=256) and seccomp filtering

• Created template build pipeline with Docker-to-ext4 conversion and snapshot generation

• Blocked cloud metadata endpoints (169.254.169.254) at both namespace and host firewall layers

Project Architecture

agent-sandbox/
├── src/
│   ├── server.ts            # HTTP server + host network setup
│   ├── app.ts               # Express routes, middleware, metrics
│   ├── session/
│   │   ├── session.ts       # State machine + reaper
│   │   └── gateway.ts       # Lazy VM creation + dispatch
│   ├── vm/
│   │   ├── vm-manager.ts    # VM lifecycle management
│   │   ├── jailer.ts        # Firecracker jailer integration
│   │   ├── templates.ts     # Template registry
│   │   ├── networking.ts    # Network namespace & egress
│   │   ├── protocol.ts      # vsock response parsing
│   │   └── cleanup.ts       # Idempotent VM teardown
│   ├── routes/
│   │   └── exec.ts          # REST API endpoints
│   └── mcp/
│       ├── server.ts        # MCP tool definitions
│       ├── routes.ts        # SSE transport + auth
│       └── stdio.ts         # Stdio transport
├── templates/
│   ├── build.sh             # Template build pipeline
│   ├── base/                # Minimal guest base
│   ├── node/                # Node.js template
│   ├── python/              # Python template
│   └── go/                  # Go template
├── sdk/
│   └── typescript/          # Client SDK
└── minimal-rootfs/
    ├── start.sh             # Guest init script
    └── runtime/
        └── runtime.js       # Guest runtime agent

Key Learnings

• Firecracker microVM architecture and snapshot mechanisms

• Linux network namespaces, veth pairs, and iptables masquerading

• vsock virtio transport for low-latency host-guest communication

• Cgroup v2 resource limits and seccomp syscall filtering

• Model Context Protocol (MCP) implementation and tooling

• Building infrastructure-as-code with security-by-default principles

• Performance profiling and microsecond-accurate benchmarking

Future Enhancements

Multi-host cluster orchestration, persistent workspace volumes, WebAssembly runtime support, and sub-20ms cold start via netlink syscalls and pre-warmed namespace pools.