RunMicrovm
Runs a new MicroVM from the specified image. The MicroVM starts in PENDING state and transitions to RUNNING once provisioning completes. To connect, generate an authentication token using CreateMicrovmAuthToken.
Request Syntax
POST /2025-09-09/microvms HTTP/1.1
Content-type: application/json
{
"clientToken": "string",
"egressNetworkConnectors": [ "string" ],
"executionRoleArn": "string",
"idlePolicy": {
"autoResumeEnabled": boolean,
"maxIdleDurationSeconds": number,
"suspendedDurationSeconds": number
},
"imageIdentifier": "string",
"imageVersion": "string",
"ingressNetworkConnectors": [ "string" ],
"kmsKeyIdentifier": "string",
"logging": { ... },
"maximumDurationInSeconds": number,
"runHookPayload": "string"
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- clientToken
-
A unique, case-sensitive identifier you provide to ensure the idempotency of the request.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Required: No
- egressNetworkConnectors
-
The list of egress network connectors available to the MicroVM at runtime.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: No
- executionRoleArn
-
The ARN of the IAM role to be assumed by the MicroVM during execution.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
arn:aws[a-z\-]*:iam::[0-9]{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+Required: No
- idlePolicy
-
Configuration to control auto-suspend and auto-resume behavior.
Type: IdlePolicy object
Required: No
- imageIdentifier
-
The identifier (ARN or ID) of the MicroVM image to run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Required: Yes
- imageVersion
-
The version of the MicroVM image to run.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+Required: No
- ingressNetworkConnectors
-
The list of ingress network connectors to configure for the MicroVM.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: No
- kmsKeyIdentifier
-
The customer managed AWS Key Management Service (AWS KMS) key that encrypts your MicroVM configuration at rest. To use this operation, you must have permission to use the key. Specify the key ARN or the alias ARN.
If you don't specify a key, your MicroVM uses an AWS owned key.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
(arn:aws[a-z-]*:kms:[a-z0-9-]+:[0-9]{12}:(key|alias)/[a-zA-Z0-9:/_-]+|alias/[a-zA-Z0-9:/_-]+|[a-zA-Z0-9-]+)Required: No
- logging
-
The logging configuration for this MicroVM instance. Specify {"cloudWatch": {"logGroup": "..."}} to stream application logs to a custom CloudWatch log group, or {"disabled": {}} to turn off logging.
Type: Logging object
Note: This object is a Union. Only one member of this object can be specified or returned.
Required: No
- maximumDurationInSeconds
-
The maximum duration in seconds that the MicroVM can exist before being terminated by the platform. Valid range: 1–28,800 (8 hours).
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 28800.
Required: No
- runHookPayload
-
Per-MicroVM initialization data delivered as the request body of the /run lifecycle hook. Use to pass tenant-specific configuration such as session IDs or secret references.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 4096.
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"egressNetworkConnectors": [ "string" ],
"endpoint": "string",
"executionRoleArn": "string",
"idlePolicy": {
"autoResumeEnabled": boolean,
"maxIdleDurationSeconds": number,
"suspendedDurationSeconds": number
},
"imageArn": "string",
"imageVersion": "string",
"ingressNetworkConnectors": [ "string" ],
"kmsKeyIdentifier": "string",
"maximumDurationInSeconds": number,
"microvmId": "string",
"startedAt": number,
"state": "string",
"stateReason": "string",
"terminatedAt": number
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- egressNetworkConnectors
-
The list of egress network connectors available to the MicroVM at runtime.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 2048.
- endpoint
-
The HTTPS endpoint URL for communicating with the MicroVM. Include a valid authentication token in the X-aws-proxy-auth header when sending requests.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
- executionRoleArn
-
The ARN of the IAM execution role assumed by the MicroVM.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
arn:aws[a-z\-]*:iam::[0-9]{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+ - idlePolicy
-
The idle policy configuration of the MicroVM.
Type: IdlePolicy object
- imageArn
-
The ARN of the MicroVM image used to run this MicroVM.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
arn:[a-z0-9-]+:lambda:[a-z0-9-]*:[a-z0-9]*:microvm-image:.+ - imageVersion
-
The version of the MicroVM image used to run this MicroVM.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - ingressNetworkConnectors
-
The list of ingress network connectors configured for the MicroVM.
Type: Array of strings
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 2048.
- kmsKeyIdentifier
-
The customer managed AWS Key Management Service (AWS KMS) key that encrypts your MicroVM configuration at rest. If you don't specify a key, your MicroVM uses an AWS owned key.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
(arn:aws[a-z-]*:kms:[a-z0-9-]+:[0-9]{12}:(key|alias)/[a-zA-Z0-9:/_-]+|alias/[a-zA-Z0-9:/_-]+|[a-zA-Z0-9-]+) - maximumDurationInSeconds
-
The maximum duration in seconds that the MicroVM can exist.
Type: Integer
- microvmId
-
The unique identifier of the MicroVM.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
- startedAt
-
The timestamp when the MicroVM first started.
Type: Timestamp
- state
-
The current lifecycle state of the MicroVM.
Type: String
Valid Values:
PENDING | RUNNING | SUSPENDING | SUSPENDED | TERMINATING | TERMINATED - stateReason
-
The reason for why the MicroVM is in the current state.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
[^\s]+ - terminatedAt
-
The timestamp when the MicroVM terminated.
Type: Timestamp
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
You do not have sufficient access to perform this action.
HTTP Status Code: 403
- ConflictException
-
The request could not be completed due to a conflict with the current state of the resource.
- resourceId
-
The identifier of the resource that caused the conflict.
- resourceType
-
The type of the resource that caused the conflict.
HTTP Status Code: 409
- InsufficientCapacityException
-
There is insufficient capacity to fulfill the request. Retry the request later.
HTTP Status Code: 500
- InternalServerException
-
An internal server error occurred. Retry the request later.
- retryAfterSeconds
-
The number of seconds to wait before retrying the request.
HTTP Status Code: 500
- ResourceNotFoundException
-
The specified resource does not exist.
- resourceId
-
The identifier of the resource that was not found.
- resourceType
-
The type of the resource that was not found.
HTTP Status Code: 404
- ServiceQuotaExceededException
-
You have exceeded a service quota for Lambda MicroVMs.
- quotaCode
-
The quota code of the exceeded service quota.
- resourceId
-
The identifier of the resource that exceeded the quota.
- resourceType
-
The type of the resource that exceeded the quota.
- serviceCode
-
The service code of the exceeded service quota.
HTTP Status Code: 402
- ThrottlingException
-
The request was denied due to request throttling. Retry the request later.
- quotaCode
-
The quota code of the throttled service quota.
- retryAfterSeconds
-
The number of seconds to wait before retrying the request.
- serviceCode
-
The service code of the throttled service quota.
HTTP Status Code: 429
- ValidationException
-
The input does not satisfy the constraints specified by the service.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: