lambda-microvm-sandbox-mcp

Give your AI coding agent a disposable Linux machine instead of your laptop.

lambda-microvm-sandbox-mcp is an MCP server that lets Claude Code, Kiro and other MCP clients create isolated sandboxes on AWS Lambda MicroVMs, run commands in them, move files in and out, and throw them away. Each sandbox is a fresh Firecracker VM in your own AWS account with git, Python, Node.js and a C toolchain preinstalled, and it boots in about two seconds.

日本語版 README

Why

• Real isolation. Commands run in a Firecracker VM, not in a container on your machine. A rm -rf or a malicious npm install cannot touch your files or your credentials: the VM has no IAM role and only reaches the internet.

• Fast and cheap. A sandbox is ready in ~2 s, suspends automatically while the agent is thinking (no compute charges), resumes in ~1 s on the next call, and is destroyed after at most 8 hours. A 2 GB sandbox costs about $0.13 per hour while running.

• Nothing to host. No servers, clusters or daemons. One setup command builds the VM image in your account; the MCP server runs locally via npx.

• Made for agents. Tools return structured results, long commands time out cleanly, output is capped, and the agent is told exactly what to do when something is missing.

Related MCP server: agent-sandbox-mcp

How it works

Claude Code / Kiro ──stdio──▶ lambda-microvm-sandbox-mcp (npx, on your machine)
                                  │  AWS SDK: RunMicrovm, tokens, suspend/resume/terminate
                                  ▼
                              AWS Lambda MicroVMs
                                  │  HTTPS + per-VM auth token + per-VM secret
                                  ▼
                              Firecracker VM (Amazon Linux 2023)
                                  └─ sandbox-agent: exec / files API, lifecycle hooks, sudo relay

The MCP server is the only thing that holds AWS credentials. It starts VMs from an image you built once, mints short-lived tokens, and talks to a small agent inside each VM. Commands run as an unprivileged sandbox user with passwordless sudo, so agents can sudo dnf install what they need without being able to kill the agent that controls the VM.

Quick start

1. Build the sandbox image in your AWS account (once, about three minutes). MicroVM images cannot be shared between accounts, so setup creates a private S3 bucket, a least-privilege build role and the image from assets shipped in the npm package. It shows the plan and asks before creating anything.

npx lambda-microvm-sandbox-mcp setup --region ap-northeast-1
npx lambda-microvm-sandbox-mcp doctor --region ap-northeast-1   # verify

Prefer infrastructure as code? Deploy cloudformation/prerequisites.yaml and pass its outputs: setup --bucket <name> --build-role-arn <arn>.

2. Register the server with your agent.

Claude Code (.mcp.json in your project):

{
  "mcpServers": {
    "lambda-sandbox": {
      "command": "npx",
      "args": ["-y", "lambda-microvm-sandbox-mcp", "--region", "ap-northeast-1"]
    }
  }
}

Kiro (.kiro/settings/mcp.json):

{
  "mcpServers": {
    "lambda-sandbox": {
      "command": "npx",
      "args": ["-y", "lambda-microvm-sandbox-mcp"],
      "env": { "AWS_REGION": "ap-northeast-1" },
      "autoApprove": ["sandbox_exec", "sandbox_read_file", "sandbox_list_files", "sandbox_status", "sandbox_list"]
    }
  }
}

The server uses your normal AWS credential chain (AWS_PROFILE, SSO, env vars).

3. Ask your agent to use it.

Create a sandbox, upload this project into it, run the test suite there and report the failures. Destroy the sandbox when you are done.

The agent will call sandbox_create, sandbox_upload_dir, sandbox_exec, read what it needs, and finish with sandbox_destroy.

Tools

Every option of the server has a flag and an environment variable; run npx lambda-microvm-sandbox-mcp --help. The full reference lives in packages/mcp-server/README.md.

Cost and limits

The agent is reminded in every tool description to destroy sandboxes it no longer needs. sandbox_list shows anything still running.

Security model

• The VM has no IAM execution role by default. Your AWS credentials stay on your machine; the sandbox can only reach the public internet (or nothing, with --no-internet-egress). Opt in to a CloudWatch-Logs-only role (setup --execution-role, then --execution-role-arn) when you want the VM's own logs.

• Every request to a VM carries a Lambda-issued token that is valid for one VM and one port, plus a per-VM secret generated at creation and delivered through the /run lifecycle hook. Neither is ever written into the image.

• Commands run as user sandbox. sudo works, but as a shim that relays to the root agent over a group-restricted unix socket, because the container runs with no_new_privileges. as_root: true on sandbox_exec does the same.

• Known sandboxes are stored in ~/.lambda-sandbox/sandboxes.json (mode 0600).

• The image is Amazon Linux 2023 minimal, so dnf is really microdnf and the default python3 is 3.9. Add what you need with sudo dnf install -y ….

Repository layout

• packages/mcp-server – the npm package: MCP server, setup, doctor, CloudFormation template.

• packages/sandbox-agent – the agent baked into the VM image and its Dockerfile.

• docs/ – research notes and the implementation log.

See CONTRIBUTING.md for development, tests, CI and releases.

License

MIT