/aws-lambda-microvms

name: aws-lambda-microvms
description: Builds, runs, debugs, and operates applications on AWS Lambda MicroVMs — Firecracker-isolated, snapshot-resumable serverless compute environments running inside a container with up to 8 hr lifetimes. Applicable when workloads need strong isolation between tenants, isolated serverless compute, sandbox compute, or secure multi-tenant execution. Also suited for AI/agent code-execution sandboxes, interactive code playgrounds and notebooks (Jupyter, REPLs, dev environments running user-supplied code), reinforcement-learning environments, multi-tenant CI executors and build runners, sessionful game or simulation servers, or isolated security scanners. Also applicable when the workload needs long-lived sessions, a real port-listening server (gRPC, WebSocket, custom TCP protocols), state preserved across periods of inactivity (suspend/resume), container-level access (FUSE, eBPF, custom syscalls), or session-affine routing.
version: 1

AWS Lambda MicroVMs

> The AWS MCP server is recommended for sandboxed execution and audit logging.

AWS Lambda MicroVMs are serverless compute environments that combine Firecracker VM isolation with container-like efficiency. Each MicroVM:

• Runs your application as a **container inside a Firecracker microVM** — you can reproduce the environment locally.
• Runs Amazon Linux 2023 as the base OS inside the MicroVM.
• Boots from a **memory + disk snapshot** captured at image build time, so application init is skipped on run.
• Has a dedicated, TLS-terminated HTTPS endpoint reachable with an auth token.
• Can be **suspended and resumed** with state preserved; lives up to 8 hours.

**Two-resource model:**

• `MicrovmImage` — a versioned artifact built from `{S3 zip with Dockerfile} + baseImageArn`. Each version has per-architecture/chipset `Build`s.
• `Microvm` — a running instance created (`RunMicrovm`) from an image version.

**Two roles:**

• `buildRoleArn` — used during image build (S3 read, CloudWatch logs, optional ECR).
• `executionRoleArn` — assumed at runtime by the running MicroVM.

When to use

Choose Lambda MicroVMs when

• **Analytics workloads** — isolated compute for data processing, ETL jobs, or query execution with strong tenant separation.
• **AI / agent code execution sandboxes** — fresh, isolated environment per session, fast resume between turns.
• **Interactive code playgrounds & notebooks** — Jupyter, REPLs, dev environments executing user code.
• **Reinforcement-learning environments** — clean per-episode envs with tool access.
• **Multi-tenant CI executors / build runners** — strong tenant isolation.
• **Game / simulation servers** — sessionful, long-lived (up to 8 hr) workloads.
• **Security scanning** — running untrusted analyzers in isolation.

In general, Lambda MicroVMs are suited for long-lived sessions, real port-listening servers (gRPC, WebSocket, custom TCP protocols), state preserved across periods of inactivity (suspend/resume), container-level access (FUSE, eBPF, custom syscalls), or session-affine routing to a specific compute environment.

Choose AWS Lambda (functions) when

• The workload fits in 15 minutes.
• Per-invocation isolation is fine; no need for session state held in memory.
• Fully automatic scaling is preferred (no `RunMicrovm` to manage).
• Event-source integrations (S3, SQS, EventBridge, etc.) drive the function.

Choose something else when

• Continuous compute beyond 8 hr → ECS / EKS / EC2.
• Lift-and-shift workloads needing kernel modifications or a non-Linux OS → EC2.

Typical workflow

0. **Check regional availability** — confirm Lambda MicroVMs is available in your target region (run `aws lambda-microvms list-managed-microvm-images`). Your S3 artifact bucket and any network connectors must be in the same region as the image. 1. **Package** an app: zip with a `Dockerfile` at the root, upload to S3 (same region as the image). 2. **Implement lifecycle hooks** (optional but recommended) — HTTP endpoints on a port you specify (commonly `9000`) for `/run`, `/resume`, `/suspend`, `/terminate`, `/ready`, `/validate`. 3. **CreateMicrovmImage** — pointing at the S3 artifact, a managed base image, and a build role. Lambda compiles the Dockerfile into an OCI image, starts your app, calls `/ready`, snapshots disk + memory, optionally validates with `/validate`. Lambda will periodically release new managed image versions, and customers should re-build using the latest version to ensure they have up to date images. 4. **RunMicrovm** — pick an image version, attach `executionRoleArn`, set `idlePolicy`, ingress/egress connectors, and (optionally) a `runHookPayload`. Receive an `endpoint` URL and `microvmId`. 5. **CreateMicrovmAuthToken** — get an auth token (max 60 min) with `allowedPorts` specifying which ports the token grants access to. Send traffic to the endpoint with `X-aws-proxy-auth: <token>`. 6. **Suspend / Resume / Terminate** — explicit APIs, or let the `idlePolicy` drive it (`maxIdleDurationSeconds`, `suspendedDurationSeconds`, `autoResumeEnabled`).

Core CLI commands

# Create an image (zip with Dockerfile at root in S3, plus a managed base image)
aws lambda-microvms create-microvm-image \
  --name my-image \
  --base-image-arn arn:aws:lambda:<region>:aws:microvm-image:al2023-1 \
  --build-role-arn arn:aws:iam::<acct>:role/MicroVMBuildRole \
  --code-artifact '{"uri":"s3://<bucket>/<key>.zip"}'

# Run a MicroVM (returns endpoint + microvmId). --image-identifier takes the
# image ARN (the bare name is rejected); --image-version is the full major.minor string.
aws lambda-microvms run-microvm \
  --image-identifier arn:aws:lambda:<region>:<acct>:microvm-image:my-image \
  --image-version 1.0 \
  --execution-role-arn arn:aws:iam::<acct>:role/MicroVMExecutionRole \
  --idle-policy '{"maxIdleDurationSeconds":900,"suspendedDurationSeconds":300,"autoResumeEnabled":true}'

# Mint an auth token and call the endpoint
TOKEN=$(aws lambda-microvms c