AWS Lambda Microvms

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 Builds.
• 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 create-microvm-auth-token \
  --microvm-identifier microvm-... --expiration-in-minutes 30 \
  --allowed-ports '[{"port":8080}]' \
  --query 'authToken."X-aws-proxy-auth"' --output text)
curl "<endpoint>/" -H "X-aws-proxy-auth: $TOKEN"

# Lifecycle
aws lambda-microvms suspend-microvm   --microvm-identifier microvm-...
aws lambda-microvms resume-microvm    --microvm-identifier microvm-...
aws lambda-microvms terminate-microvm --microvm-identifier microvm-...

See references/getting-started.md for the full walkthrough including --hooks config and lifecycle hooks.

Hook configuration

Hooks are organized into two groups under the --hooks parameter:

microvmImageHooks (build-time)

Recommendation: Implement the image build hooks (/ready and /validate) for best performance. They enable the platform to capture a complete snapshot and prefetch the portions accessed at run time.

Why implement /ready? It signals the platform that your application has fully booted. Without it, the snapshot may be taken mid-initialization, meaning the cached state is incomplete and every run repeats part of the boot sequence.

Why implement /validate? It lets the platform verify the snapshot is correct, and also samples which portions of the snapshot are accessed during RunMicrovm. This allows the platform to prefetch those portions on future launches, reducing cold-start times.