xiry.

Development · Framework

Browser Use Agent Sandbox Architecture

Architecture pattern for securely running code-executing agents inside isolated micro-VMs

From the Xiry library · Updated 11 October 2026

An infrastructure blueprint from Browser Use detailing how to isolate autonomous, code-executing agents from sensitive systems. Instead of sandboxing individual tools, the entire agent runs inside a secretless Unikraft micro-VM that routes all network calls, credentials, and state through a stateless control plane proxy.

The framework

How We Built Secure, Scalable Agent Sandbox Infrastructure (Larsen Cundric, Browser Use): from AWS Lambda browser-only agents to Unikraft micro-VMs with a control plane.

PROBLEM: agent loop ran on the same backend as the REST API — redeploys kill running agents; memory-hungry agents slow the API.

TWO ISOLATION PATTERNS when an agent can run arbitrary code:

- Pattern 1: Isolate the tool — agent on your infra, dangerous ops (code exec, terminal) run in a separate sandbox called via HTTP. Security ✓, Decoupled ✗, Scalable ✗.

- Pattern 2: Isolate the agent — whole agent runs in a sandbox with zero secrets; it talks to the outside world through a control plane holding all credentials. Security ✓, Decoupled ✓, Scalable ✓. They moved from Pattern 1 to Pattern 2.

SANDBOX: same container image everywhere — Unikraft micro-VM in production (<1s boot, provisioned via Unikraft Cloud REST API on bare metal in AWS), Docker locally/in evals, switched by sandbox_mode: 'docker' | 'ukc'. Scale-to-zero: idle VM suspends and resumes instantly. Distributed across multiple Unikraft metros. Sandbox receives only 3 env vars: SESSION_TOKEN, CONTROL_PLANE_URL, SESSION_ID.

HARDENING (before any agent code runs):

1. Bytecode-only execution — compile Python to .pyc during Docker build, delete all .py files.

2. Privilege drop — entrypoint starts as root to read root-owned bytecode, then setuid/setgid to a 'sandbox' user.

3. Environment stripping — after reading the 3 env vars into Python, delete them from os.environ; VM sits in private VPC.

CONTROL PLANE: stateless FastAPI proxy service — every sandbox request hops through it (LLM calls, S3 uploads, billing), authenticated via Bearer {session_token}.

- LLM proxying: sandbox sends only new messages; control plane owns full conversation history in DB, reconstructs context, forwards to provider → sandbox is stateless/disposable. Control plane enforces cost caps and billing.

- File sync: /workspace changes synced to S3 via presigned URLs — sandbox calls POST /presigned-urls, control plane issues session-scoped S3 URLs, sandbox uploads/downloads directly without AWS credentials.

- Gateway protocol: AgentGateway(Protocol) with invoke_llm() and persist_messages(); ControlPlaneGateway (HTTP) in prod, DirectGateway (in-memory) in dev/evals — agent code can't tell which.

SCALING: stateless control plane behind a load balancer (ECS Fargate in private subnets behind ALB), auto-scaled on CPU; sandboxes scale independently via Unikraft per-session VMs.

KEY TAKEAWAY: your agent should have nothing worth stealing and nothing worth preserving. Tradeoff: extra network hop + 3 services instead of 1; latency is noise vs LLM response times.

What it's for

  • Secure infrastructure against arbitrary code execution by untrusted AI agents
  • Prevent credential exfiltration by keeping API keys out of execution environments
  • Decouple long-running agent workflows from main application redeploys

Key points

  • Full-agent isolation where the execution environment contains zero persistent secrets
  • Stateless control plane proxy that manages LLM calls, billing, and conversation state
  • Micro-VM execution using Unikraft for sub-second cold starts and suspend-to-zero capabilities
  • Bytecode-only Python hardening with automatic environment variable stripping on startup
  • Presigned S3 URL pattern for workspace file synchronization without baking AWS credentials into VMs
  • Gateway protocol abstraction allowing seamless switching between local Docker development and production micro-VMs

Pricing

Free

Details

Type
Framework
Category
Development
Topic
System Architecture
Open source
No
Platforms
Linux, Self-hosted
For
Backend and AI engineers building platforms that execute untrusted code or run autonomous agents
Alternative to
E2B, Modal, Fly.io Machines
Tags
agents, sandboxing, unikraft, security, microvms, python

Why it was saved

  • @larsencc, 27 February 2026: A concrete, production-proven blueprint for running millions of code-executing agents securely and scalably.

Related

Updated