AWS Lambda MicroVMs

Firecracker-based serverless sandboxes (GA June 2026) with suspend/resume up to 8h. Control plane via @aws-sdk/client-lambda-microvms; you bake a small runner into the image.

Website Docs

Installation

@aws-sdk/client-lambda-microvms is an optional peer dependency, used for the control plane (launch / suspend / resume / terminate). The data plane (exec, files) is plain fetch to the microVM's endpoint.

pnpm add sbox-sdk @aws-sdk/client-lambda-microvms

How it works

AWS Lambda MicroVMs give you isolation, lifecycle, and a dedicated HTTPS endpoint — but the in-VM exec/filesystem protocol is defined by your image. So this adapter speaks a tiny "runner" protocol over the endpoint, and you bake a reference runner into your MicroVM image once.

Build a MicroVM image from a Dockerfile + the reference runner, upload to S3, and call CreateMicrovmImage → note the image ARN.
The adapter calls RunMicrovm (launch from that ARN), CreateMicrovmAuthToken (JWE), then Suspend/Resume/Terminate.
Each op is an HTTPS request to the microVM endpoint with X-aws-proxy-auth + X-aws-proxy-port headers, routed to the runner's POST /sbox/exec, /sbox/fs/read, /sbox/fs/write.

The reference runner (a dependency-free Node server) ships in the package at sbox-sdk/src/aws-lambda/runner/ — server.mjs, Dockerfile, and a README with the exact build & create-microvm-image commands. The runner runs inside the isolated MicroVM; executing arbitrary commands is its purpose.

Usage

import { createSandboxClient } from "sbox-sdk";
import { awsLambda } from "sbox-sdk/aws-lambda";

const client = createSandboxClient({
  provider: awsLambda({
    imageIdentifier:
      "arn:aws:lambda:us-east-1:123456789012:microvm-image:sbox-runner",
    region: process.env.AWS_REGION!,
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  }),
});

const sandbox = await client.create();
const res = await sandbox.commands.run("echo hello");
await sandbox.files.write("/tmp/data.txt", "hi");

await sandbox.pause(); // SuspendMicrovm — memory + disk preserved (up to 8h)
await sandbox.resume(); // ResumeMicrovm
await sandbox.destroy(); // TerminateMicrovm

credentials and region resolve through the standard AWS SDK chain (environment variables, shared config, or an instance/task role) when those options are omitted.

template overrides the image ARN per create(); otherwise the imageIdentifier option is used.

Authentication

Standard AWS credentials + a MicroVM image ARN.

Authentication variables for the aws-lambda adapter.
Option	Env var	Required	Description
`imageIdentifier`	—	required	ARN of the MicroVM image (or pass `template` per `create()`).
`region`	`AWS_REGION`	required	AWS region the MicroVMs run in.
`credentials.accessKeyId`	`AWS_ACCESS_KEY_ID`	required	AWS access key id.
`credentials.secretAccessKey`	`AWS_SECRET_ACCESS_KEY`	required	AWS secret access key.
`credentials.sessionToken`	`AWS_SESSION_TOKEN`	optional	Session token for temporary credentials.

Credentials and region resolve through the standard AWS SDK chain (environment variables, shared config, or an instance/task role) when the `credentials` / `region` options are omitted.

Options

Prop

Type

Capabilities

Capability	Level	Notes
`list` / `region`	native
`pause`	native	`Suspend` preserves memory + disk
`stop`	unsupported	only run / suspend / terminate
`streaming`	emulated	runner returns buffered output
`filesUpload`	native	via the runner
`exposePort`	native	endpoint + `X-aws-proxy-port` + JWE
`codeInterpreter`	unsupported
`snapshot` / `fork`	unsupported	the image is the build-time snapshot

preservesMemoryOnPause is true; previewModel is tunnel.