agent-microvm

Isolated AWS microVM sandboxes for AI agents.

Python SDK · CLI · MCP server · AWS microVMs

Getting started · Demo · MCP setup · Contributing

Easy, fast, isolated microVM sandboxes for untrusted workloads (AI agents, user code, CI jobs) using 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.

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

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

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. vmnest 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 + vmnest 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.

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 (vmnest 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. vmnest 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. vmnest stop suspends with memory and disk intact, vmnest start resumes, vmnest 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 (vmnest 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. vmnest 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.

• Demo
• Why agent-microvm?
  • Use cases
• Components
• Architecture
• Prerequisites
• 1. Install the SDK/CLI
• 2. Configure and deploy the infrastructure
• 3. Use the SDK
• 4. Use the vmnest 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

graph TD
    subgraph app [Your Application]
        SDK["agent_sandbox SDK / vmnest 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

• 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 — vmnest infra provisions everything with boto3 (a core dependency) and tracks state in a local JSON file.

The package is published on PyPI as vmnest (Python import: agent_sandbox; command: vmnest). Install with pip:

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

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

git clone https://github.com/jnh12/agent-microvm.git
cd agent-microvm

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 vmnest command on your PATH. Verify with vmnest --help.

Infrastructure support (vmnest 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.

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 vmnest infra create it.

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

sandbox.yaml (created by vmnest infra init):

project: vmnest
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

vmnest 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: vmnest infra refresh, vmnest infra destroy, vmnest infra output [NAME]. Use vmnest infra up --rebuild to force a new MicroVM image version even when one is already active.

vmnest 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 vmnest infra output --all.

vmnest infra records what it created — and whether each resource was created by it (managed) versus reused from your sandbox.yaml — in a local JSON file at ~/.agent_sandbox/infra-state.json (override with AGENT_SANDBOX_INFRA_STATE). vmnest infra destroy only tears down resources it manages, so reused resources are left untouched. This file also holds the outputs (image_arn, execution_role_arn, build_bucket) that the SDK/CLI auto-wire from.

After vmnest infra up, the CLI auto-reads image_arn, execution_role_arn, and any network outputs from the stack. For the raw SDK you can either rely on that or export env vars explicitly:

export AGENT_SANDBOX_IMAGE_ARN=$(vmnest infra output image_arn)
export AGENT_SANDBOX_EXECUTION_ROLE_ARN=$(vmnest infra output execution_role_arn)
python examples/run_code.py   # -> Hello from a microVM!

On Windows PowerShell, use $env: instead of export:

$env:AGENT_SANDBOX_IMAGE_ARN = (vmnest infra output image_arn)
$env:AGENT_SANDBOX_EXECUTION_ROLE_ARN = (vmnest infra output execution_role_arn)
python examples/run_code.py

import asyncio
from agent_sandbox import Sandbox

async def main():
    sandbox = await Sandbox.create("my-sandbox", cpus=1, memory=512)
    out = await sandbox.exec("python", ["-c", "print('hi')"])
    print(out.stdout_text)
    await sandbox.stop()

asyncio.run(main())

After vmnest infra up, --image/--role are auto-read from the stack, so most commands need no flags:

# lifecycle (a named sandbox tracked in local state)
vmnest create app                    # auto-wired image/role from infra outputs
vmnest exec app -- python -c "import this"
vmnest ls                            # all tracked sandboxes + live status
vmnest ps app                        # one sandbox's status
vmnest inspect app                   # full MicroVM info as JSON
vmnest logs app                      # CloudWatch logs (best-effort)
vmnest metrics app                   # CloudWatch metrics (best-effort)
vmnest stop app                      # suspend (memory/disk preserved)
vmnest start app                     # resume
vmnest rm app                        # terminate + drop from local state

# ephemeral one-shot (image ARN is a required positional — not auto-wired)
vmnest run "$(vmnest infra output image_arn)" -- python -c "print('one-shot')"

# serve a port from inside the sandbox on localhost (see section 5)
vmnest forward app --remote-port 8000 --local-port 8000

# images
vmnest image build ./guest --name my-guest --bucket "$(vmnest infra output build_bucket)"
vmnest image ls                      # your images (--managed for AWS base images, --json for raw)
vmnest image rm <image-arn>

# infrastructure
vmnest infra init | preview | up | refresh | destroy | output [NAME]

# run the MCP server over stdio (see the MCP section)
vmnest mcp

Common flags

• vmnest create / vmnest run: --image/-i, --role, --cpus, --memory/-m (default 512), --region, and --egress-connector <arn> / --egress/-e (attach the egress connector from infra outputs).
• Every lifecycle/status command takes --region.
• vmnest logs: --log-group to override the CloudWatch group.
• vmnest image ls: --managed (AWS base images), --json (raw output).
• vmnest forward: --remote-port/-r (required), --local-port/-l, --no-verify-tls, --poll-interval. The reserved lifecycle-hook port (AGENT_SANDBOX_HOOK_PORT, default 9000) is rejected — see Guest agent & lifecycle hooks.
• vmnest infra up: --file/-f is repeatable and accepts directories (multi-project), plus --stack/-s, --rebuild, --parallelism/-p.

vmnest create resolves image/role from the flag → env var (AGENT_SANDBOX_IMAGE_ARN / AGENT_SANDBOX_EXECUTION_ROLE_ARN) → vmnest infra outputs, in that order, so after vmnest infra up most commands need no flags. vmnest run is the exception: it takes the image ARN as a required positional argument and is not auto-wired.

The CLI keeps a local name → MicroVM map at ~/.agent_sandbox/state.json (override with AGENT_SANDBOX_STATE), since AWS has no concept of sandbox names.

image inspect and image prune are available only as MCP tools, not as vmnest CLI commands.

Lambda MicroVMs use network connectors (not subnets/security groups) for ingress/egress, attached at run_microvm time. By default MicroVMs get managed egress (e.g. INTERNET_EGRESS) from the image, so vmnest create/run need no network config.

For custom VPC egress, provision a connector in sandbox.yaml's network.egress block (vmnest infra up creates/records egress_network_connector_arn), then attach it per sandbox with vmnest create app --egress (pulls the connector from infra outputs) or --egress-connector <arn>. The SDK accepts ingress_network_connectors / egress_network_connectors directly for finer control (e.g. SHELL_INGRESS).

• vmnest stop suspends (resume with vmnest start); vmnest rm terminates.
• vmnest image build zips a directory, uploads it to S3, and registers a MicroVM image (there is no local OCI cache on AWS).
• vmnest logs/vmnest metrics read CloudWatch (best-effort; override the log group with --log-group).

vmnest forward runs a local reverse proxy so you can reach a service running inside a sandbox from your browser. The examples/serve_fastapi.py script demonstrates the full flow: it writes a small FastAPI app into the VM, starts uvicorn, and proxies http://localhost:8000 to it.

python examples/serve_fastapi.py            # then open http://localhost:8000

# or forward a port for a service you started yourself:
vmnest forward app --remote-port 8000 --local-port 8000

The SDK and CLI are configured mainly through sandbox.yaml + vmnest infra outputs, so most setups need no environment variables at all. The two below are the only values that must be resolvable; everything else is an optional override.

Required — each needs one of: a CLI flag, an environment variable, or an vmnest infra up output (auto-wired). After vmnest infra up both are auto-wired.

AWS credentials and region come from the standard boto3 chain (AWS_REGION / AWS_DEFAULT_REGION, AWS_PROFILE, instance role, etc.). The region must be one where Lambda MicroVMs is available (see Prerequisites).

Optional overrides

The MCP server adds a further set of AGENT_SANDBOX_MCP_* tuning knobs — see Configuration under the MCP section below.

vmnest ships an MCP server (agent_sandbox_mcp) that lets AI agents create isolated microVM sandboxes, execute code, manage files, read logs, and monitor resources. It mirrors the tool-naming conventions and response patterns of microsandbox-mcp, but is implemented in Python with FastMCP on top of the agent_sandbox SDK.

The MCP server ships in the optional mcp extra. It must be installed — without it vmnest mcp exits immediately and the client reports "Failed to connect". Install it one of these ways:

From PyPI:

pip install "vmnest[mcp]"

Source checkout (development):

uv sync --extra mcp
# or, with pip: pip install -e '.[mcp]'

Global tool (so vmnest is on your PATH everywhere) — include the [mcp] extra:

# from a source checkout (editable — tracks your working tree):
uv tool install --editable ".[mcp]" --force
# or from PyPI (published as `vmnest`):
uv tool install "vmnest[mcp]"

Gotcha: keep the [mcp] extra every time you (re)install the global tool. uv tool install --reinstall . without [mcp] drops the mcp package and breaks vmnest mcp — re-run the command above with ".[mcp]" to fix it.

Verify it's installed and reachable:

vmnest mcp     # starts the stdio server (Ctrl+C to stop). An "mcp not available"
            # message instead means the [mcp] extra is missing — see above.
which vmnest   # e.g. ~/.local/bin/vmnest — use this absolute path if your MCP client
            # runs in a different environment and can't find vmnest on its PATH.

Provision the backend first (vmnest infra up) so image/role ARNs resolve, or set AGENT_SANDBOX_IMAGE_ARN / AGENT_SANDBOX_EXECUTION_ROLE_ARN (see Environment variables) — otherwise the client connects but tool calls error at runtime.

The server runs over stdio and can be launched three ways — use whichever your client makes easiest:

• vmnest mcp — via the bundled CLI (recommended).
• vmnest-mcp — the standalone console script (same server).
• python -m agent_sandbox_mcp — module form, handy when vmnest isn't on PATH.

All the client snippets below use vmnest mcp. If your MCP client runs in a different environment than your shell (so vmnest isn't on its PATH), swap in the absolute path to vmnest, or use uv run --directory /path/to/agent-microvm vmnest mcp. Wire the required ARNs through the client's env block when they aren't already exported, as shown in the generic example.

Claude Code

claude mcp add agent-sandbox -- vmnest mcp

Claude Desktop — add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "vmnest",
      "args": ["mcp"]
    }
  }
}

Cursor — add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "vmnest",
      "args": ["mcp"]
    }
  }
}

VS Code — add to .vscode/mcp.json:

{
  "servers": {
    "agent-sandbox": {
      "command": "vmnest",
      "args": ["mcp"]
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json (same mcpServers shape as Cursor/Claude Desktop above).

Goose — Goose uses a YAML config. Either run goose configure → Add Extension → Command-line Extension and enter vmnest mcp, or add an entry to ~/.config/goose/config.yaml:

extensions:
  agent-sandbox:
    enabled: true
    type: stdio
    cmd: vmnest
    args: [mcp]

pi / any other stdio client — most clients share the same shape. This generic block also shows wiring the required ARNs via env when they aren't exported in the client's environment:

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "vmnest",
      "args": ["mcp"],
      "env": {
        "AGENT_SANDBOX_IMAGE_ARN": "arn:aws:lambda:us-east-1:...:microvm-image/...",
        "AGENT_SANDBOX_EXECUTION_ROLE_ARN": "arn:aws:iam::...:role/agent-sandbox-exec"
      }
    }
  }
}

Every tool returns a JSON envelope: { "ok": true, "data": ... } on success or { "ok": false, "error": { "code", "message", ... } } on failure. Large command output, logs, and file reads are capped by default and include truncation metadata (truncated, total_bytes, returned_bytes) when shortened.

Runtime

Sandbox Lifecycle

Command Execution

Logs

Filesystem

Metrics

Images

The server reuses the SDK/CLI variables from Environment variables (image/role ARN, region, egress connector, TLS, workdir) and adds these MCP-specific tuning knobs. If you run a custom guest image, also see Bring your own guest image → If you use MCP for the env values the MCP process must resolve independently:

The server stays a thin adapter over the agent_sandbox SDK and only exposes what the AWS Lambda MicroVMs backend supports today. The following microsandbox-mcp capabilities are intentionally not implemented because the backend has no first-class API for them:

• Volumes (volume_*) — no named-volume API.
• Snapshots (snapshot_*) — only suspend/resume exist, not content snapshots.
• SSH / SFTP (sandbox_ssh_*, sandbox_sftp_*) — no SSH subsystem in the guest.
• Streaming exec sessions (sandbox_exec_start / _poll / _write_stdin / _signal / _close) and sandbox_drain — agentd's /v1/exec is a blocking, one-shot call, so interactive/streamed sessions are not possible without guest-side changes.

uv sync --extra dev --extra mcp     # installs mcp + deps
uv run pytest tests/mcp -q          # unit + stdio smoke tests (no AWS)
AGENT_SANDBOX_MCP_E2E=1 uv run python tests/mcp/e2e.py   # live e2e (needs infra)

The guest image runs two servers in one process (python -m agentd.serve):

• agentd on port 8080 — the application API (/v1/exec, /v1/fs/*, /healthz) the SDK/CLI reach through the MicroVM's auth-token proxy.
• lifecycle hooks on port 9000 — called only by the AWS Lambda MicroVMs platform (never by your clients) at image build and MicroVM state transitions.

The hooks make sandboxes faster and safer with no action on your part:

Hooks are baked into the image at build time, so rebuild to pick them up on an existing stack: vmnest infra up --rebuild.

The hook port is reserved. vmnest forward refuses --remote-port 9000 — the lifecycle plane is the platform's private channel and must never be client-reachable, and auth tokens are scoped to the app port only.

Ports are configurable (defaults 8080 / 9000). Override the guest with AGENTD_PORT / AGENTD_HOOK_PORT (baked via the Dockerfile) and the SDK/CLI with the matching AGENT_SANDBOX_AGENT_PORT / AGENT_SANDBOX_HOOK_PORT. Keep the two hook-port values in sync — the SDK tells the platform which port to call, and the guest must bind the same one.

You don't have to use the bundled guest. vmnest image build ./my-guest (or image.guest_dir in sandbox.yaml) accepts any directory with a Dockerfile. But the SDK, vmnest CLI, and the MCP server all reach into the VM through the same small HTTP agent (agentd), so a custom image must honor that contract or exec/fs — and therefore every MCP sandbox_* tool — will fail to connect. To keep a custom image working:

1. Serve the agentd API on the agent port. Your image must answer POST /v1/exec, POST /v1/fs/read, POST /v1/fs/write, and GET /healthz on AGENTD_PORT (default 8080). Easiest path: base your Dockerfile on the bundled guest, or COPY the bundled agentd package + serve.py into your image and keep its CMD (python -m agentd.serve).
2. Keep the agent port aligned on both sides. The guest binds AGENTD_PORT; the SDK/CLI/MCP scope auth tokens to AGENT_SANDBOX_AGENT_PORT. If you change one, change the other — a mismatch means the proxy can't route to your agent.
3. Lifecycle hooks are opt-in. To keep them, run agentd.serve (it starts the hook server too), EXPOSE + bind AGENTD_HOOK_PORT (default 9000), keep AGENT_SANDBOX_HOOK_PORT in sync, and build with --hooks (vmnest infra up does this). Drop them and the sandbox still works — you just lose the faster-start / per-VM-uniqueness benefits (see above).

The MCP server runs as its own process, launched by your MCP client — it does not inherit your shell's environment. So any value you overrode for the guest must also be resolvable in the MCP process, wired through the client's env block (see the config examples under Use it from an AI agent (MCP)):

A mismatch between the port the MCP process scopes tokens to and the port your custom agent actually binds is the usual cause of MCP sandbox_exec / sandbox_fs_* "failed to connect" errors. When in doubt, keep the defaults (8080 / 9000) and set only the two ARNs.

You can exercise agentd and the hook server without AWS:

docker build --platform linux/arm64 -t agent-sandbox-guest ./guest
docker run --rm -p 8080:8080 -p 9000:9000 agent-sandbox-guest
curl localhost:8080/healthz
curl -s localhost:8080/v1/exec -H 'content-type: application/json' \
  -d '{"command":"python","args":["-c","print(1+1)"]}'

# lifecycle-hook server (normally the platform calls these, not you):
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  localhost:9000/aws/lambda-microvms/runtime/v1/ready   # -> 200 once agentd is up

Volumes, PTY/interactive sessions, network policy / TLS-MITM, and streaming exec (HTTP/2 / WebSocket) are not yet implemented. See sdk/agent_sandbox/ for extension points, and SDK Gaps for how these surface (or don't) in the MCP server.

Contributions are welcome! See CONTRIBUTING.md for how to set up a dev environment, run the tests and linter, and open a pull request.

Apache-2.0 — see LICENSE.