Lifecycle model

Two state machines (image and MicroVM) plus the lifecycle hook contract your application can optionally implement.

Image state machine

Image-level state:

CREATING ──▶ CREATED ──▶ DELETING

Version-level state (state + status):

state: PENDING ──▶ IN_PROGRESS ──▶ SUCCESSFUL
                              └─▶ FAILED

status: ACTIVE | INACTIVE

A single image version can produce multiple Build records — one per (architecture, chipset, chipsetGeneration). Each build has its own buildState: PENDING → IN_PROGRESS → SUCCESSFUL | FAILED. List with list-microvm-image-builds.

UpdateMicrovmImageVersion switches a version's status between ACTIVE and INACTIVE — RunMicrovm will only resolve ACTIVE versions when no explicit imageVersion is supplied.

MicroVM state machine

PENDING
   │
   ▼
RUNNING ◀──── (auto-resume on ingress, or ResumeMicrovm)
   │  ▲
   ▼  │
SUSPENDING ──▶ SUSPENDED
                  │
                  ▼ (after suspendedDurationSeconds, or TerminateMicrovm)
              TERMINATING ──▶ TERMINATED

Triggers:

RunMicrovm → PENDING → RUNNING.
Idle for maxIdleDurationSeconds of no proxy traffic → SUSPENDING → SUSPENDED. Or call SuspendMicrovm.
Ingress traffic on the endpoint with autoResumeEnabled: true, or ResumeMicrovm → RUNNING.
SUSPENDED for suspendedDurationSeconds → terminated.
Maximum lifetime maximumDurationInSeconds (cap 28,800 s = 8 hr) reached → terminated.
TerminateMicrovm from anywhere.

Idle is measured by traffic through the proxy endpoint. If your app does outbound work but receives no inbound traffic, the platform will count it as idle. For background workers, set high maxIdleDurationSeconds or disable auto-suspend by omitting idlePolicy in the request.

Lifecycle hooks

Your application can implement HTTP endpoints that Lambda invokes at lifecycle transitions. Hooks are opt-in per image via the --hooks parameter. You must specify the port your hooks listen on (commonly 9000).

Image build hooks

Hook	Path	When invoked	Timeout field	Use it for
`/ready`	`POST /aws/lambda-microvms/runtime/v1/ready`	During image build, before snapshot capture	`readyTimeoutInSeconds` (1–3600)	Confirm app initialized; fail the build if app is broken
`/validate`	`POST /aws/lambda-microvms/runtime/v1/validate`	After build, on a test MicroVM run from the snapshot	`validateTimeoutInSeconds` (1–3600)	End-to-end smoke test of the snapshot

Implementing image build hooks is recommended for performance — they ensure your application is fully initialized before the snapshot is captured, resulting in faster runs.

MicroVM hooks

Hook	Path	When invoked	Timeout field	Use it for
`/run`	`POST /aws/lambda-microvms/runtime/v1/run`	Once, immediately after a MicroVM is run (resumed from snapshot)	`runTimeoutInSeconds` (1–60)	Create per-VM unique state, fetch secrets, register with discovery. Should be quick — not for long-running work
`/resume`	`POST /aws/lambda-microvms/runtime/v1/resume`	After `SUSPENDED` → `RUNNING`	`resumeTimeoutInSeconds` (1–60)	Re-establish connections, generate new randomness if your application relies on non-CSPRNGs
`/suspend`	`POST /aws/lambda-microvms/runtime/v1/suspend`	Just before `RUNNING` → `SUSPENDED`	`suspendTimeoutInSeconds` (1–60)	Return 200 only when the app is ready to be suspended. Customer decides the strategy: wait for in-flight work to drain within the timeout, or return immediately
`/terminate`	`POST /aws/lambda-microvms/runtime/v1/terminate`	Just before termination	`terminateTimeoutInSeconds` (1–60)	Flush logs, persist state, deregister

If you use microVM hooks, you must implement the /ready microVM image hook. This ensures your application has booted and can receive hook events.

Always set explicit timeout values in --hooks when creating the image — especially for /ready (init) and /run//resume (any per-VM init work).

Configuring hooks (image creation)

--hooks '{
  "port": 9000,
  "microvmImageHooks": {
    "ready": "ENABLED",
    "readyTimeoutInSeconds": 60,
    "validate": "ENABLED",
    "validateTimeoutInSeconds": 10
  },
  "microvmHooks": {
    "run": "ENABLED",
    "runTimeoutInSeconds": 2,
    "resume": "ENABLED",
    "resumeTimeoutInSeconds": 2,
    "suspend": "ENABLED",
    "suspendTimeoutInSeconds": 5,
    "terminate": "ENABLED",
    "terminateTimeoutInSeconds": 5
  }
}'

A hook left at its default DISABLED is not called even if the application implements the path.

Hook contract

Return HTTP 200 when the hook has completed successfully. For /ready and /validate, return 503 if the application needs more time — the platform will keep retrying until the configured timeout elapses. Returning 503 quickly is preferred over blocking the request until ready: a blocked call holds the connection open and can consume the entire timeout window in one attempt instead of letting the platform poll.
- During image build, a /ready failure (non-200/503 or timeout) fails the build.
- At runtime, a hook failure may cause RunMicrovm to fail or transition the MicroVM through TERMINATING with stateReason set.
The runHookPayload you pass to RunMicrovm is delivered as the request body of /run.

Sequence: run + ingress + idle + resume + terminate

                    Lambda                       Your app
                       │                             │
RunMicrovm ───────────▶│                             │
                       │   resume snapshot           │
                       │   POST /run (runHookPayload)│
                       │────────────────────────────▶│ 200
                       │                             │
                client ──── HTTPS ingress ──────────▶│ (request handled)
                       │ ... no traffic for          │
                       │   maxIdleDurationSeconds ...  │
                       │   POST /suspend             │
                       │────────────────────────────▶│ 200
                       │   suspend (snapshot RAM+disk)
                       │                             │
                client ──── HTTPS ingress ──────────▶│ (auto-resume if enabled)
                       │   resume                    │
                       │   POST /resume              │
                       │────────────────────────────▶│ 200
                       │   ... eventually ...        │
TerminateMicrovm ─────▶│   POST /terminate           │
                       │────────────────────────────▶│ 200
                       │   stop                      │

Idle policy fields

The idlePolicy block itself is optional on RunMicrovm — omit it to disable idle-based auto-suspend entirely. If you supply the block, all three fields below are required:

Field	Range	Notes
`maxIdleDurationSeconds`	≥60	Required if `idlePolicy` is supplied. Idle threshold from last proxy traffic.
`suspendedDurationSeconds`	≥0	Required if `idlePolicy` is supplied. Time-to-terminate while suspended. `0` means "terminate immediately on suspend."
`autoResumeEnabled`	bool	Required if `idlePolicy` is supplied. If true, proxy resumes the VM transparently when traffic arrives at its endpoint.

maximumDurationInSeconds is not an idlePolicy field — it is a separate top-level RunMicrovm flag that sets a hard wall-clock lifetime regardless of activity.

Hook implementation tips

Bind to 0.0.0.0 on the configured port. Lambda calls hooks over the guest's network namespace; localhost-only listeners are unreachable.
Run hooks in a separate thread / event loop from your application server. /suspend should still answer 200 even if your main worker pool is busy.
Keep /run and /resume fast. These hooks are notification mechanisms. If your application needs to run long-running workflows (> 60s) in response, do so asynchronously.
Don't use /run for long-running init. That work belongs at image build time so it's captured in the snapshot. Avoid generating random data at build time — if unique random state is needed, invalidate and re-generate using a CSPRNG on /run.
Make hooks idempotent. Lambda may retry /suspend or /terminate under failure conditions.

Where to go next

Per-VM uniqueness (entropy, secrets, env vars vs. runHookPayload): snapshots-and-uniqueness.md
Hook-related failure modes: troubleshooting.md

/aws-lambda-microvms

referenceslifecycle-model.md