import type { Credentials } from "@distilled.cloud/aws/Credentials";
import type * as microvms from "@distilled.cloud/aws/lambda-microvms";
import type { Region } from "@distilled.cloud/aws/Region";
import type * as Bundle from "alchemy/Bundle/Bundle";
import { Platform } from "alchemy/Platform";
import type { Main } from "alchemy/Platform";
import type { Resource } from "alchemy/Resource";
import type { ProcessContext } from "alchemy/Runtime/Process";
import * as Effect from "effect/Effect";
import type { PolicyStatement } from "../IAM/Policy.ts";
import type { Role } from "../IAM/Role.ts";
import type { Providers } from "../Providers.ts";
import { makeMicrovmRuntimeContext, MicrovmImageTypeId } from "./MicrovmRuntimeContext.ts";
/**
* The IAM permissions a build role needs: read the code artifact from the
* Assets bucket(s) and write build logs to CloudWatch. Used to auto-grant a
* {@link Role} passed as `buildRole`.
*/
const buildRolePolicyStatements: PolicyStatement[] = [
{
Effect: "Allow",
Action: ["s3:GetObject"],
Resource: ["arn:aws:s3:::alchemy-assets-*-an/*"],
},
{
Effect: "Allow",
Action: ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
Resource: ["arn:aws:logs:*:*:log-group:/aws/lambda/microvms/*"],
},
];
export { MicrovmImageTypeId } from "./MicrovmRuntimeContext.ts";
export interface MicrovmImageProps {
/**
* The name of the MicroVM image. Must be 1-64 characters of letters,
* numbers, hyphens, or underscores. If omitted, a unique name is generated.
* Changing the name replaces the image.
*/
name?: string;
/**
* **Effectful mode.** Entrypoint file for an Effect-native HTTP server,
* typically `import.meta.filename`. Alchemy bundles it (with its bindings),
* generates a Dockerfile, zips the result, and uploads it as the
* `codeArtifact`.
*/
main?: string;
/**
* **External mode.** A build-context directory containing your Dockerfile and
* the files it copies. Alchemy zips and uploads it; AWS runs your Dockerfile.
* @default "./"
*/
context?: string;
/**
* The Dockerfile. In effectful mode this is an inline base string (defaults
* to `FROM public.ecr.aws/lambda/microvms:al2023-minimal`). In external mode
* it is a path relative to {@link context} (defaults to `<context>/Dockerfile`).
*/
dockerfile?: string;
/**
* The port the in-VM HTTP server listens on (effectful mode).
* @default 8080
*/
port?: number;
/**
* The JS runtime to bundle for (effectful mode).
* @default "node"
*/
runtime?: "bun" | "node";
/**
* Extra module ids to leave external when bundling (effectful mode).
*/
external?: string[];
/**
* Bundler configuration for {@link main} (effectful mode). Unused
* code is tree-shaken. `effect`, alchemy, and `@distilled.cloud` are
* marked pure so unused parts prune more aggressively. List extra
* packages with `pure.packages`, or disable with `pure: false`.
*
* The program is minified with `keepNames` by default. On the Node
* runtime a source map ships with it and stack traces map back to your
* source; Bun ignores external source maps, so its traces keep function
* names but point into the bundle. Set `output: { minify: false }` to
* ship readable code.
*/
build?: Bundle.BundleConfig;
/**
* The base MicroVM image to build on top of — either its ARN or another
* {@link MicrovmImage} instance. If omitted, the latest AWS-managed `al2023`
* base is used (discover bases with {@link microvms.listManagedMicrovmImages}).
*/
baseImage?: string | MicrovmImage;
/**
* The specific version of the base MicroVM image.
*/
baseImageVersion?: string;
/**
* The IAM role Lambda assumes to build the image (read the code artifact,
* write build logs) — either its ARN or an {@link Role} instance. When you
* pass a `Role`, the required S3 (Assets bucket) and CloudWatch-logs
* permissions are granted to it automatically via a binding, so you don't
* have to write the inline policy yourself. Required for all builds.
*/
buildRole?: string | Role;
/**
* **Prebuilt mode.** A code artifact (S3 zip path or ECR image URI) to use
* as-is, instead of bundling (`main`) or building a context (`context`).
*/
codeArtifact?: microvms.CodeArtifact;
/**
* A description of the image version.
*/
description?: string;
/**
* Logging configuration for the MicroVM runtime/build. Specify exactly one of
* `cloudWatch` or `disabled`.
*/
logging?: microvms.Logging;
/**
* The names/ARNs of egress network connectors available to the MicroVM at
* runtime (see {@link NetworkConnector}).
*/
egressNetworkConnectors?: string[];
/**
* The CPU configurations the image supports.
*/
cpuConfigurations?: microvms.CpuConfiguration[];
/**
* The resource requirements (e.g. minimum memory) for the MicroVM.
*/
resources?: microvms.Resources[];
/**
* Additional OS capabilities granted to the MicroVM runtime.
*/
additionalOsCapabilities?: microvms.Capability[];
/**
* Lifecycle hook configuration for the MicroVM and its image.
*/
hooks?: microvms.Hooks;
/**
* Environment variables set in the MicroVM runtime environment. Capability
* bindings (e.g. S3/DynamoDB clients) also contribute entries here during
* plan; all of them are written to the image's environment.
*/
env?: Record<string, any>;
/**
* Tags to apply to the image.
*/
tags?: Record<string, string>;
/**
* @internal Platform-managed: the bundled runtime entrypoint.
*/
exports?: string[] | Record<string, any>;
/**
* @internal Platform-managed: signals a non-Effect-native (external) image.
*/
isExternal?: boolean;
}
export interface MicrovmImage extends Resource<
"AWS.Lambda.MicrovmImage",
MicrovmImageProps,
{
/** The ARN of the MicroVM image. */
imageArn: string;
/** The name of the MicroVM image. */
name: string;
/** The current state of the image (e.g. `CREATED`, `CREATING`). */
state: microvms.MicrovmImageState;
/** The image version produced by the most recent build. */
imageVersion?: string;
/** The latest version that built successfully. */
latestActiveImageVersion?: string;
/** The latest version that failed to build, if any. */
latestFailedImageVersion?: string;
/** When the image was created (ISO 8601). */
createdAt?: string;
/** When the image was last updated (ISO 8601). */
updatedAt?: string;
/**
* The resolved code artifact and its build identity hash. `contentHash`
* covers only the bundled program / packaged context (no props), so a
* content-only edit is detectable at plan time before the props resolve.
*/
codeArtifact?: { uri?: string; hash?: string; contentHash?: string };
},
{
env?: Record<string, any>;
policyStatements?: PolicyStatement[];
},
Providers
> {}
export type MicrovmImageServices = Credentials | Region;
export type MicrovmImageShape = Main<MicrovmImageServices>;
/**
* A Lambda **MicroVM image** — a Firecracker snapshot that boots a fully
* initialized application in milliseconds. The model is *image-then-launch*:
* you create an image once (this resource), then launch isolated, stateful
* MicroVM instances from it at runtime (one per end-user/session) with the
* {@link RunMicrovm} binding from a Lambda Function.
*
* ### How the build works <!-- api-prose -->
*
* The build runs **server-side on AWS** — there is no local Docker. You supply
* a *code artifact* (a zip of a Dockerfile + your code) and a *base image*
* (`baseImage`); AWS runs your Dockerfile on top of the base, initializes
* the app, and takes a Firecracker snapshot. The build is asynchronous: the
* provider uploads the artifact, calls `CreateMicrovmImage`/`UpdateMicrovmImage`,
* and polls until the image reaches `CREATED`/`UPDATED` (or surfaces the build
* failure). Build logs stream to CloudWatch at `/aws/lambda/microvms/<name>`.
*
* Alchemy produces the code artifact for you in three ways, selected by which
* prop you set (`main` → `context` → `codeArtifact.uri`):
*
* - **Effectful** (`main`): write the in-VM HTTP server in TypeScript as an
* Effect. Alchemy bundles it (with its capability bindings), generates a
* Dockerfile on the MicroVM base, zips both, and uploads to the Assets bucket.
* - **External** (`context`/`dockerfile`): bring your own Dockerfile + build
* context (any language). Alchemy zips the directory and uploads it.
* - **Prebuilt** (`codeArtifact.uri`): point at an existing S3 zip or ECR image
* URI; nothing is built or uploaded.
*
* Re-deploys only trigger a new build when the artifact's content hash or a
* build-affecting prop changes; otherwise the image is left untouched.
*
* ### Prerequisites <!-- api-prose -->
*
* - A **build role** (`buildRole`) Lambda assumes to read the code artifact and
* write build logs. Pass a {@link Role} instance and the required permissions
* are granted automatically — see the example below.
* - A **bootstrapped Assets bucket** (`alchemy provider aws bootstrap`) for effectful /
* external modes, which upload the artifact to S3.
* - The account must be **onboarded to the Lambda MicroVM preview**.
*
*
* ### Creating the Build Role
* Pass a bare {@link Role} as `buildRole` and the MicroVM image grants
* everything it needs via a binding: the trust policy (so Lambda can assume it)
* plus the S3 (Assets bucket) and CloudWatch-logs permissions (folded into an
* `alchemy-bindings` inline policy). You don't write any policy yourself.
* **Example:** Bare build role
* ```typescript
* const buildRole = yield* AWS.IAM.Role("MicrovmBuildRole", {});
*
* // Pass the role instance; trust + permissions are attached for you.
* const image = yield* AWS.Lambda.MicrovmImage("Sandbox", {
* main: import.meta.filename,
* buildRole,
* });
* ```
*
* ### Effectful MicroVMs
* Write the in-VM server in TypeScript. Alchemy bundles `main` and bakes it into
* the image; the server listens on `port` (default 8080), which becomes the
* MicroVM `endpoint`.
* **Example:** In-VM HTTP server (single file)
* ```typescript
* export default class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()(
* "Sandbox",
* { main: import.meta.filename, buildRole },
* Effect.gen(function* () {
* return {
* fetch: Effect.gen(function* () {
* const request = yield* HttpServerRequest;
* return HttpServerResponse.text(`hello from ${request.url}`);
* }),
* };
* }),
* ) {}
* ```
*
* **Example:** With capability bindings and env vars
* ```typescript
* export default class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()(
* "Sandbox",
* {
* main: import.meta.filename,
* buildRole,
* runtime: "bun",
* env: { LOG_LEVEL: "info" },
* },
* Effect.gen(function* () {
* // bindings are bundled into the image and resolved at runtime
* const getObject = yield* AWS.S3.GetObject(bucket);
* return {
* fetch: Effect.gen(function* () {
* const obj = yield* getObject({ key: "data.json" });
* return HttpServerResponse.json(yield* obj.json);
* }),
* };
* }).pipe(Effect.provide(AWS.S3.GetObjectHttp)),
* ) {}
* ```
*
* **Example:** Class + `.make()` (two files, for a Lambda orchestrator)
* When a Lambda Function imports the image to bind its instance operations, keep
* the class (a typed handle) and the `.make()` runtime in separate files so the
* orchestrator's bundle doesn't pull in the VM's runtime deps.
* ```typescript
* // sandbox.ts — imported by the orchestrator
* export class Sandbox extends AWS.Lambda.MicrovmImage<Sandbox>()("Sandbox") {}
*
* // sandbox.live.ts — provided on the Stack; bundled into the image.
* // Must be the `default` export: the bundler resolves the image entrypoint
* // from the code artifact's default export.
* export default Sandbox.make(
* { main: import.meta.filename, buildRole },
* Effect.gen(function* () {
* return { fetch: Effect.gen(function* () {
* return HttpServerResponse.text("ok");
* }) };
* }),
* );
* ```
*
* ### Tagged RPC
* Beyond (or instead of) a raw `fetch` handler, an image can expose a typed
* **RPC `Shape`** as the second type parameter. The in-VM runtime serves those
* methods over an `/__rpc__/*` protocol and falls through to `fetch` for every
* other request, so an image can offer BOTH a typed RPC surface and ordinary
* HTTP routes. A caller gets a fully-typed client with {@link connectMicrovm}:
* value methods `yield*` as `Effect`s, streaming methods pipe as `Stream`s.
* **Example:** Define a tagged-RPC image (RPC + fetch)
* ```typescript
* // sandbox.ts — the typed handle imported by the orchestrator Lambda
* export class Sandbox extends AWS.Lambda.MicrovmImage<
* Sandbox,
* { hello: (message: string) => Effect.Effect<string> }
* >()("Sandbox") {}
*
* // sandbox.live.ts — provided on the Stack; bundled into the image (default export)
* export default Sandbox.make(
* { main: import.meta.filename, buildRole },
* Effect.gen(function* () {
* return {
* // RPC method — reached with `connectMicrovm` below
* hello: (message: string) => Effect.succeed(`hello, ${message}!`),
* // raw HTTP route — reached with a plain HTTPS request to the endpoint
* fetch: Effect.gen(function* () {
* const request = yield* HttpServerRequest;
* const url = new URL(request.url, "http://microvm");
* return HttpServerResponse.json({ path: url.pathname });
* }),
* };
* }),
* );
* ```
*
* **Example:** Call the RPC method from a Lambda
* `connectMicrovm` builds the typed stub over an `HttpClient` (provide
* `FetchHttpClient.layer` for the request scope), pointing at the running
* MicroVM's `endpoint` and authenticating with the `authToken` headers.
* ```typescript
* const vm = yield* runMicrovm({});
* // ...wait until `vm.state` is RUNNING (poll `getMicrovm`)...
* const { authToken } = yield* createAuthToken({
* microvmIdentifier: vm.microvmId,
* expirationInMinutes: 5,
* allowedPorts: [{ port: 8080 }], // the in-VM server's port
* });
*
* const sandbox = yield* AWS.Lambda.connectMicrovm(Sandbox, {
* endpoint: vm.endpoint,
* authToken,
* });
* const reply = yield* sandbox.hello("world"); // "hello, world!"
* ```
*
* **Example:** Call the same MicroVM's `fetch` route directly
* For the raw HTTP path, send the auth token as request headers via
* {@link microvmAuthHeaders}.
* ```typescript
* const client = yield* HttpClient.HttpClient;
* const res = yield* client.get(`https://${vm.endpoint}/echo?message=hi`, {
* headers: AWS.Lambda.microvmAuthHeaders(authToken),
* });
* const body = yield* res.json;
* ```
*
* ### Bundling & Tree-shaking
* `main` is bundled with rolldown at deploy time. Unused code is
* tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
* pure so unused parts prune more aggressively. Your app is not
* marked pure.
*
* **Example:** Mark additional packages as pure
* Only list packages with no top-level side effects.
* ```typescript
* {
* main: import.meta.url,
* build: {
* pure: { packages: ["my-lib", "@my-scope/*"] },
* },
* }
* ```
*
* **Example:** Turn it off
* ```typescript
* {
* main: import.meta.url,
* build: { pure: false },
* }
* ```
*
* ### External Images (your own Dockerfile)
* Bring a build context directory containing a Dockerfile (any language).
* Alchemy zips and uploads it; AWS runs your Dockerfile. Your Dockerfile should
* build on a MicroVM-compatible base (e.g.
* `FROM public.ecr.aws/lambda/microvms:al2023-minimal`).
* **Example:** Flask app from a Dockerfile
* ```typescript
* const image = yield* AWS.Lambda.MicrovmImage("Flask", {
* context: `${import.meta.dirname}/app`, // dir with Dockerfile + app.py
* buildRole,
* });
* ```
* **Example:** Custom Dockerfile path within the context
* ```typescript
* const image = yield* AWS.Lambda.MicrovmImage("Worker", {
* context: `${import.meta.dirname}/app`,
* dockerfile: "docker/worker.Dockerfile", // relative to `context`
* buildRole,
* });
* ```
*
* ### Prebuilt Artifacts
* Skip the build entirely and point at an artifact you already produced.
* **Example:** From an existing S3 zip
* ```typescript
* const image = yield* AWS.Lambda.MicrovmImage("Prebuilt", {
* codeArtifact: { uri: "s3://my-bucket/app.zip" }, // or an ECR image URI
* buildRole,
* });
* ```
*
* ### Sizing and Base Image
* `baseImage` defaults to the latest AWS-managed `al2023` base (discovered
* via `listManagedMicrovmImages`). Override it, and tune CPU/memory, explicitly.
* **Example:** Pin the base image and resources
* ```typescript
* const image = yield* AWS.Lambda.MicrovmImage("Sized", {
* main: import.meta.filename,
* buildRole,
* baseImage: "arn:aws:lambda:us-east-1:aws:microvm-image:al2023-1",
* cpuConfigurations: [{ architecture: "ARM_64" }],
* resources: [{ minimumMemoryInMiB: 2048 }],
* });
* ```
*
* ### Logging
* **Example:** Stream runtime + build logs to a custom CloudWatch group
* ```typescript
* const image = yield* AWS.Lambda.MicrovmImage("Logged", {
* main: import.meta.filename,
* buildRole,
* logging: { cloudWatch: { logGroup: "/aws/microvm/my-app" } },
* // or disable: logging: { disabled: {} }
* });
* ```
*
* ### VPC Egress
* Give the MicroVM a managed egress path into your VPC with a
* {@link NetworkConnector} (reference it by ARN).
* **Example:** Image-level egress connector
* ```typescript
* const egress = yield* AWS.Lambda.NetworkConnector("Egress", {
* subnetIds: [subnet.subnetId],
* securityGroupIds: [sg.groupId],
* operatorRole: operatorRole.roleArn,
* });
*
* const image = yield* AWS.Lambda.MicrovmImage("Connected", {
* main: import.meta.filename,
* buildRole,
* egressNetworkConnectors: [egress.networkConnectorArn],
* });
* ```
*
* ### Launching MicroVMs
* The image is just the template. Launch and drive instances from a Lambda
* Function using the per-operation bindings ({@link RunMicrovm},
* {@link GetMicrovm}, {@link CreateAuthToken}, {@link TerminateMicrovm}, …).
* Each binding's IAM policy is scoped to this image automatically.
* **Example:** Run a MicroVM, call its RPC, and tear it down
* Always terminate the MicroVM you launched — wrap the work in
* `Effect.ensuring` so a failure (or a client retry) never leaks a running
* MicroVM against your account's memory quota. Give the Function a generous
* `timeout` since it waits for the MicroVM to reach RUNNING in-line.
* ```typescript
* export default class Api extends AWS.Lambda.Function<Api>()(
* "Api",
* { main: import.meta.filename, functionUrl: true, timeout: Duration.seconds(120) },
* Effect.gen(function* () {
* const runMicrovm = yield* AWS.Lambda.RunMicrovm(Sandbox);
* const getMicrovm = yield* AWS.Lambda.GetMicrovm(Sandbox);
* const createAuthToken = yield* AWS.Lambda.CreateAuthToken(Sandbox);
* const terminateMicrovm = yield* AWS.Lambda.TerminateMicrovm(Sandbox);
* return {
* fetch: Effect.gen(function* () {
* const vm = yield* runMicrovm({
* idlePolicy: {
* maxIdleDurationSeconds: 900,
* suspendedDurationSeconds: 300,
* autoResumeEnabled: true,
* },
* });
* return yield* Effect.gen(function* () {
* // wait until the MicroVM is RUNNING before connecting
* yield* getMicrovm({ microvmIdentifier: vm.microvmId }).pipe(
* Effect.flatMap((m) =>
* m.state === "RUNNING"
* ? Effect.void
* : Effect.fail(new Error(`microvm ${m.state}`)),
* ),
* Effect.retry({ schedule: Schedule.spaced("2 seconds"), times: 30 }),
* );
* const { authToken } = yield* createAuthToken({
* microvmIdentifier: vm.microvmId,
* expirationInMinutes: 5,
* allowedPorts: [{ port: 8080 }],
* });
* const sandbox = yield* AWS.Lambda.connectMicrovm(Sandbox, {
* endpoint: vm.endpoint,
* authToken,
* });
* const reply = yield* sandbox.hello("world");
* return yield* HttpServerResponse.json({ reply });
* }).pipe(
* // terminate on success OR failure — never leak a running MicroVM
* Effect.ensuring(
* terminateMicrovm({ microvmIdentifier: vm.microvmId }).pipe(
* Effect.ignore,
* ),
* ),
* // the in-VM endpoint calls need an HttpClient for this scope
* Effect.provide(FetchHttpClient.layer),
* );
* }),
* };
* }).pipe(
* Effect.provide(
* Layer.mergeAll(
* AWS.Lambda.RunMicrovmHttp,
* AWS.Lambda.GetMicrovmHttp,
* AWS.Lambda.CreateAuthTokenHttp,
* AWS.Lambda.TerminateMicrovmHttp,
* ),
* ),
* ),
* ) {}
* ```
*
* @resource
*/
export const MicrovmImage: Platform<
MicrovmImage,
MicrovmImageServices,
MicrovmImageShape,
ProcessContext
> = Platform(MicrovmImageTypeId, {
createRuntimeContext: makeMicrovmRuntimeContext,
// When `buildRole` is a Role instance, grant it the build permissions via a
// binding so the user doesn't have to author the inline policy.
onCreate: (_resource, props: MicrovmImageProps) =>
props.buildRole && typeof props.buildRole !== "string"
? props.buildRole.bind`Allow(${_resource}, AWS.Lambda.MicrovmImage.build)`({
// Grant the build permissions...
policyStatements: buildRolePolicyStatements,
// ...and the trust statement, so a build role passed as a bare
// `Role` (no `assumeRolePolicyDocument`) can be assumed by Lambda.
assumeRolePolicyStatements: [
{
Effect: "Allow",
Principal: { Service: "lambda.amazonaws.com" },
Action: ["sts:AssumeRole"],
},
],
})
: Effect.void,
});