agent-sandbox-os

Easy, fast, isolated microVM sandboxes for untrusted workloads (AI agents, user code, CI jobs), backed by AWS Lambda MicroVMs and provisioned with bare boto3 (no external IaC engine required).

Each sandbox is a Firecracker MicroVM with VM-level isolation, snapshot-based fast start, a dedicated HTTPS endpoint, and suspend/resume for up to 8 hours.

Demo

Both recordings are unedited captures of the real CLI against real AWS.

Install, configure, provision — uv pip install "asbox[mcp]", the whole of sandbox.yaml, then asb infra up building the MicroVM image and wiring up the role and build bucket:

Boot a sandbox and serve an app out of it — asb create (a ~3 second boot), write a FastAPI app into the VM with asb exec, start uvicorn, then asb forward the port to localhost and curl it:

Why agent-sandbox-os?

Agentic workloads run untrusted, model-generated code. The agent decides at runtime what to execute — shell out, install a package, hit the network — so the blast radius is unknown ahead of time. Containers share the host kernel; for code you didn't write, that boundary is often not strong enough, and standing up your own VM fleet to get real isolation is a lot of undifferentiated ops work.

AWS Lambda MicroVMs give each sandbox a Firecracker microVM with hardware-virtualized, VM-level isolation while staying serverless — no clusters, nodes, or capacity to manage. agent-sandbox-os wraps that backend so an agent can treat a sandbox as a disposable tool:

• Safe by construction — every command runs in a per-session microVM, isolated from the host and from other sessions. Ideal for AI-generated code, user submissions, and CI jobs.
• Fast and stateful — snapshot-based fast start, plus suspend/resume for up to 8 hours, so an agent can pause a long-running session and resume it later with memory and disk intact.
• Serverless economics — pay for what you use; no idle VM fleet sitting between agent runs.
• Batteries included — one agent_sandbox SDK + asb CLI, a per-sandbox HTTPS endpoint, and a built-in MCP server so Claude, Cursor, Goose, and other agents can create, run, and manage sandboxes as native tools.
• No IaC engine — infrastructure is provisioned with bare boto3 and tracked in a local state file; nothing else to install or operate.

Use cases

Developer workloads that outgrow the laptop. Multi-agent orchestration is memory-hungry — a handful of concurrent agents, each with its own toolchain and build tree, will exhaust local RAM long before it exhausts your patience. Each sandbox gets its own CPU/memory allocation in AWS (asb create app --cpus 2 -m 2048), so you scale out by adding microVMs rather than by buying RAM.

Local coding agents that run unattended. The agent shells out, installs packages, and rewrites files inside the microVM — not on your machine. It can't touch your home directory, and you don't have to sit there approving each command to be sure of that.

Network you actually control. By default a sandbox gets managed egress from the image. Define a VPC egress connector in sandbox.yaml (network.egress) and every outbound connection leaves through a security group you own, so you decide which hosts and ports the workload can reach. Ingress is opt-in per sandbox via the SDK's ingress_network_connectors (e.g. SHELL_INGRESS) — nothing is reachable from outside unless you attach a connector. See Networking.

Credentials scoped by IAM, not baked into the image. Attach managed policies to the MicroVM execution role with role.extra_policy_arns in sandbox.yaml; code inside the VM then reads from Secrets Manager, SSM Parameter Store, or S3 through that role. No long-lived keys travel into the sandbox, and the blast radius of a compromised sandbox is whatever that one role allows.

View a sandbox dev server in your local browser. asb forward app -r 8000 -l 8000 runs a local reverse proxy into the VM, so a React, Vite, or FastAPI dev server running inside the sandbox opens at http://localhost:8000. See Serve a web app from a sandbox.

Suspend, resume, and terminate out of the box. asb stop suspends with memory and disk intact, asb start resumes, asb rm tears down. A session can stay alive across up to 8 hours of work without you paying for it to idle.

A sandbox per code session. Named sandboxes are tracked in local state, so several concurrent sessions — one per agent, per branch, per experiment — each get their own microVM, isolated from one another and independently suspendable.

One image, many VMs. Build the guest image once (asb image build ./guest), then create as many microVMs from it as you need — different workloads, same reproducible base, no rebuild per sandbox.

One command to stand up the backend. asb infra up provisions the MicroVM image, execution role, S3 build bucket, and optional network connectors with bare boto3, recording everything in a local state file.

Contents

• Demo
• Why agent-sandbox-os?
  • Use cases
• Components
• Architecture
• Prerequisites
• 1. Install the SDK/CLI
• 2. Configure and deploy the infrastructure
• 3. Use the SDK
• 4. Use the asb CLI
• 5. Serve a web app from a sandbox
• Environment variables
• Use it from an AI agent (MCP)
• Guest agent & lifecycle hooks
• Bring your own guest image
• Local guest-image smoke test
• Status / not yet implemented
• Contributing
• License

Components

| Component | Description | | --- | --- | | Runtime | AWS Lambda MicroVMs (managed Firecracker) via boto3 lambda-microvms | | Guest agent | guest/agentd — FastAPI agentd (exec/fs API on port 8080) plus a lifecycle-hook server (port 9000), run together via agentd.serve and baked into the MicroVM image | | SDK | agent_sandbox.Sandbox.create(...) | | Transport | agent_sandbox.agent_client.AgentClient (HTTPS + X-aws-proxy-auth) | | CLI | asb | | Infrastructure | asb infra (bare boto3 provisioner, agent_sandbox.infra) driven by sandbox.yaml; PyYAML ships in the base install | | MCP server | agent_sandbox_mcp (FastMCP server, optional [mcp] extra, launched with asb mcp) |

Architecture

graph TD
    subgraph app [Your Application]
        SDK["agent_sandbox SDK / asb CLI"]
    end
    subgraph aws [lambda-microvms control plane]
        CP["run / suspend / resume / terminate + auth token"]
    end
    subgraph vm [MicroVM from snapshot]
        AG["agentd: exec, fs.read, fs.write (:8080)"]
        HK["lifecycle hooks: ready / validate / run / resume / suspend / terminate (:9000)"]
    end
    SDK -->|"boto3"| CP
    CP -->|"id + HTTPS URL"| SDK
    SDK -->|"HTTPS + X-aws-proxy-auth"| AG
    CP -->|"lifecycle hooks (platform-only)"| HK

Prerequisites

• Python 3.11+, uv
• AWS CLI v2 recent enough to include lambda-microvms, with credentials configured
• Docker (only to test the guest image locally; the build itself happens in AWS)
• A region where Lambda MicroVMs is available: us-east-1, us-east-2, us-west-2, eu-west-1, ap-northeast-1. Pick any of these via region: in sandbox.yaml or the standard AWS_DEFAULT_REGION / AWS_REGION environment variable.

No IaC engine or external CLI is required — asb infra provisions everything with boto3 (a core dependency) and tracks state in a local JSON file.

1. Install the SDK/CLI

The package is published on PyPI as asbox (the import name and asb CLI are unchanged). Install with pip:

pip install asbox            # SDK + CLI + infra (PyYAML is a base dependency)
pip install "asbox[mcp]"     # + MCP server (FastMCP) — see the MCP section below
pip install "asbox[isal]"    # + faster ISA-L guest-image zipping (optional accelerator)

Or work from a clone with uv (recommended for development):

git clone https://github.com/dhanababum/agent-sandbox-os.git
cd agent-sandbox-os

uv sync                 # SDK + CLI + infra
uv sync --extra mcp     # + MCP server (FastMCP)
uv sync --extra isal    # + faster ISA-L guest-image zipping
# or editable with pip:
#   pip install -e .          # SDK + CLI + infra
#   pip install -e ".[mcp]"   # + MCP server

This installs the asb command on your PATH. Verify with asb --help.

Infrastructure support (asb infra, reading sandbox.yaml) is included in the base install — no extra needed. The legacy [infra] extra still resolves but is now an empty no-op.

2. Configure and deploy the infrastructure

All infrastructure variables live in a single sandbox.yaml. Each resource is reuse-or-create: set an existing id/arn to reuse it, or leave it empty to have asb infra create it.

asb infra init            # scaffold sandbox.yaml (edit as needed)
asb infra preview         # see what will change
asb infra up              # create/update; prints outputs (image_arn, role, ...)

sandbox.yaml (created by asb infra init):

project: agent-sandbox-os
stack: dev
region: us-east-1

image:
  name: agent-sandbox-guest
  guest_dir: ./guest            # zipped -> S3 -> create_microvm_image
  base_image_arn: ""            # empty -> newest managed base image (e.g. al2023)
  base_image_version: ""        # optional

role:
  arn: ""                       # set -> reuse; empty -> create
  name: agent-sandbox-exec
  extra_policy_arns: []         # optional managed policy ARNs to attach

bucket:
  name: ""                      # set -> reuse; empty -> create

network:                        # OPTIONAL. Omit entirely for default public egress.
  egress:                       # VPC egress network connector (reuse-or-create).
    connector_arn: ""           # set -> reuse; empty -> create a VPC_EGRESS connector
    name: agent-sandbox-egress  # name for the created connector (+ SG)
    vpc_id: ""                  # empty -> default VPC
    subnet_ids: []              # subnet ids or Name tags; empty -> discover in VPC
    security_group_id: ""       # set -> reuse; empty -> create egress-only SG
    operator_role_arn: ""       # set -> reuse; empty -> create NetworkConnectorOperatorRole

asb infra is a bare-boto3 provisioner (under agent_sandbox.infra); each resource is created idempotently and recorded in a local JSON state file, so no IaC engine or external CLI is needed.

Other infra commands: asb infra refresh, asb infra destroy, asb infra output [NAME]. Use asb infra up --rebuild to force a new MicroVM image version even when one is already active.

asb infra output prints the current stack's outputs labeled with their project/stack (empty {} when nothing is provisioned or after destroy). With several sandbox.yaml files — one project each — pick one with -f <file> / -s <stack>, or list them all with asb infra output --all