microvm-ctl

The control and execution plane for AWS Lambda MicroVMs. Build a snapshot image from a Dockerfile, launch Firecracker microVMs in seconds, scale a fleet inside the quotas your account actually has, call into every VM over its authenticated endpoint, watch the whole thing live, and hand a VM a task from Step Functions, Lambda durable functions, or any orchestrator through a lease the VM completes itself. One Python SDK, one mvm command.

pip install microvm-ctl          # https://pypi.org/project/microvm-ctl/

mvm bootstrap                              # one time: S3 artifact bucket + build/execution IAM roles
mvm image build my-sandbox ./my-app        # Dockerfile at ./my-app root -> runnable snapshot
mvm run my-sandbox --wait                  # RunMicrovm, then poll to RUNNING
mvm call <microvm-id> /execute -X POST -d '{"code":"print(2+2)"}'
mvm scale my-sandbox 10                    # converge the fleet, throttled to your applied quota
mvm top --watch                            # live state table

To see it used for real first, jump to the eight examples.

Why this exists

Lambda MicroVMs exposes the primitive under Lambda itself: a Firecracker VM with a full AL2023 userland, a dedicated HTTPS endpoint, and a lifecycle you control (run, suspend, resume, terminate). The service deliberately stops there. There is no load balancer (one endpoint per VM), no fleet abstraction, no token management, no dashboard, and a fresh account runs quotas far below the published defaults. microvm-ctl fills that gap.

The lambda-microvms botocore service model ships inside the package, so the plane works on whatever boto3 you already have.

Measured, not quoted

Every number in this repo comes from the live service in us-east-1. The harness that produced them is benchmarks/benchmark.py; run it against your own account.

The SDK in 20 lines

from microvm import PlaneConfig, FleetManager, EndpointClient, Fleet
from microvm.fleet import IdlePolicy

cfg = PlaneConfig()                      # region, profile, bucket, roles from MVM_* env vars
fm = FleetManager(cfg)                   # throttled to your account's applied TPS

vm = fm.run("my-sandbox",
            idle_policy=IdlePolicy(max_idle=300, suspended_for=3600, auto_resume=True),
            run_payload='{"tenant_id": "acme"}')

client = EndpointClient(cfg, vm.microvm_id)
print(client.post("/execute", json={"code": "print(41+1)"}).json())

fleet = Fleet(fm, "my-sandbox")
fleet.scale_to(20, wait_running=True)    # one call, token-bucketed, jittered retries
fleet.suspend_all()                      # park the fleet: snapshot storage billing only
fleet.drain()                            # terminate every member

Inside the VM, declare the lifecycle with the injected hook runtime. There is nothing to install in the image.

from microvm_hooks import HookApp
app = HookApp()

@app.on_ready
def ready(ctx):
    warm_caches()
    return True                          # 200 means "snapshot me now"

@app.on_run
def run(ctx):                            # every clone, before traffic; RNG is reseeded for you
    load_tenant(ctx.get("runHookPayload"))

@app.route("POST", "/execute")
def execute(body, headers):
    return 200, {"out": sandbox_exec(body["code"])}

app.serve(port=8080)

What the CLI looks like

mvm quotas shows the difference between the published defaults and what your account can actually do. This is a fresh account: one launch per second and 8 GB of total microVM memory.

mvm image ls after building the eight example images from the companion repo.

mvm cost prices a session shape from the published rates. This is the 30 minutes active plus 8 hours suspended shape on a 2 GB VM with the measured 0.61 GB snapshot.

The playground

mvm playground opens a local web app that drives everything above against the live service: build images, run and scale fleets, call VMs, tail logs, price sessions, run a parameterised benchmark, and watch every AWS API call the process makes in a trace. A dry-run switch turns each mutating action into a printout of the exact request it would send. See docs/playground.md.

mvm playground            # http://127.0.0.1:8765

Documentation

• Quickstart: from an empty account to a serving VM, with the environment variables explained.
• CLI reference: every mvm command and flag.
• SDK reference: PlaneConfig, ImageBuilder, FleetManager, Fleet, EndpointClient, FleetMonitor, CostModel.
• Architecture: the two planes, the lifecycle state machine, the fleet design decisions, and the security model.
• The hook contract: what each hook is for and what breaks when you ignore it.
• Quotas and cost: the quota walls, what counts against them, and the cost model with worked examples.
• Troubleshooting: the errors I hit on the live service and what each one meant.
• The playground: the local web app over the whole SDK, and how to host it.
• Integrations: the lease contract for handing a VM to Step Functions, Lambda durable functions, or your own orchestrator, and what the plane should own.

See it working: thirteen examples and the article series

The fastest way to understand the plane is to read the apps built on it. The companion repo awesome-microvm holds thirteen production-shaped examples, each a Dockerfile plus a single-file app, deployed and recorded on the live service:

The four-part article series Building on AWS Lambda MicroVMs on the AWS Builder Center walks through them:

1. Control and scale AWS Lambda MicroVMs with microvm-ctl: this plane and its measurements.
2. Seven workloads Lambda could never run, until MicroVMs: the first seven examples through build, run, cost, and gotchas.
3. A kernel for every customer: scaling AI agents to 1,000 tenants on AWS Lambda MicroVMs with microvm-ctl: the multi-tenant finale with the decision guide.
4. Hand a task to a MicroVM from anywhere: one lease, Step Functions, durable functions, or your own controller: the lease contract, Step Functions, durable functions, your own controller, and leases at scale.

The article sources and a long-form deep dive per example live under awesome-microvm/blog.

Every lease scenario also runs live, on Step Functions and on a Lambda durable function, in microvm-handoff-demo: nine scenarios on both orchestrators plus one lease from the CLI, with the execution histories, VM and orchestrator logs, benchmarks, and console screenshots checked in. Its first pass ran on 0.3.0 and found the two things that became 0.3.1: a typed failure whose VM Step Functions never terminated, and a 30 s heartbeat interval against a 30 s heartbeat timeout that lost a durable callback before the first heartbeat landed.

Requirements and regions

Python 3.9 or newer on the machine running the plane. The VMs themselves are ARM64 (Graviton) only, so audit binary wheels before you build an image. The service is available in us-east-1, us-east-2, us-west-2, eu-west-1, and ap-northeast-1.

Credits and inspiration

This project grew out of lambda-microvm-starter by Alexey Vidanov, the one-command on-ramp that deploys any Dockerfile to a Lambda MicroVM behind a public CloudFront URL. His starter kit and its troubleshooting notes were the first working map of the service I had, and several of the gotchas documented here were first written down there. microvm-ctl takes the next step from one deployed app to fleets, tokens, quotas, and cost, and I am grateful for the ground he covered first.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the local test loop (no AWS account needed for the unit tests) and the conventions used in this repo.

License

Apache-2.0