dots.v2.microvms.post()
Generated on 13 Nov 2026
from DoTs version
v1.24.0
Usage
client.v2.microvms.post(body: Microvm_create, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | MicrovmsPostResponse>Description
To create a MicroVM, send a POST request to /v2/microvms.
name and source are required. Set source.oci_ref to create the MicroVM from a
linux/amd64 container image, or source.checkpoint_id to create it from a checkpoint.
With oci_ref, region and size are also required.
A MicroVM created from an image is returned with state set to creating. Poll
GET /v2/microvms/{microvm_id} until state is running. A MicroVM created from a
checkpoint is usually returned already running.
All settings are fixed at creation. There is no update endpoint.
Parameters
namestring requiredExample:
example-microvmThe name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
sourceobject requiredWhat the MicroVM runs. Set exactly one of
oci_reforcheckpoint_id.Show child properties
ociRefstring optionalExample:
docker.io/library/nginx:latestA reference to a
linux/amd64container image in the formregistry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.checkpointIdstring optionalExample:
01a0ed98-0a74-75dd-a625-e4856adbc298The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.
regionstring optionalExample:
mkc1The slug of the region to create the MicroVM in. Required with
source.oci_ref.sizeobject optionalThe MicroVM's size.
cpuandmemorymust be one of the pairs1/2048,2/4096,8/16384, or16/32768. The size sets the disk, which is returned in responses.Show child properties
cpuinteger requiredExample:
1The number of vCPUs.
memoryinteger requiredExample:
2048The amount of memory, in MiB.
diskinteger optional read-onlyExample:
50The size of the disk, in GB. Set by the size.
networkingstring optionalpublicsends outbound traffic through a shared NAT gateway.vpcplaces the MicroVM in the VPC network set byvpc_uuid.vpcUuidstring optionalExample:
5a4981aa-9653-4bd1-bef5-d6bff52042e4The ID of a VPC network in the same region that belongs to your team. When
networkingisvpcand this is omitted, the team's default VPC is used.egressPolicyobject optionalAn outbound allow list. A destination that matches any rule is allowed;
default_actiondecides every other destination. Only valid withpublicnetworking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injectedHTTP_PROXY/HTTPS_PROXYenvironment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, exactly as supplied. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.Show child properties
defaultActionstring optionalWhat to do with a destination no rule matches.
denyrefuses it (an HTTP request gets a 403 and a TLS connection is closed).rulesarray of objects optionalThe destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an
iprule. Each rule sets exactly one ofdomainorip.Show child properties
domainstring optionalExample:
api.example.comAn exact host such as
api.example.com, or a wildcard such as*.example.com.ipstring optionalExample:
203.0.113.5An exact IP address. CIDR ranges are not supported.
projectIdstring optionalExample:
4de7ac8b-495b-4884-9a69-1050c6793cd6The project to place the MicroVM in. Omit to use the team's default project. A project that does not belong to the team is rejected.
ingressboolean optionalExample:
trueWhether to create the MicroVM with a default public URL. Defaults to
true. Set tofalseto create the MicroVM without one; URLs can be added later with POST/v2/microvms/{microvm_id}/urls.autoPauseobject optionalAutomatic pause settings. A MicroVM always pauses after it is idle for
idle_timeout. Sendingenabledset tofalseis rejected.Show child properties
enabledboolean optionalExample:
trueWhether auto-pause is on. Always
true.idleTimeoutstring optionalExample:
5m0sHow long the MicroVM is idle before it pauses, as a duration such as
30s,5m, or1h. Defaults to5m. The maximum is4h. Responses show the duration in the form5m0s.
autoResumeboolean optionalExample:
trueWhether an HTTP request, command, or console session resumes the MicroVM when it is paused. Set to
falseto require a manual resume.httpPortinteger optionalExample:
80The guest port the workload serves HTTP on. Defaults to
8080. Not returned in responses. When creating from a checkpoint withoutports, must be one of the checkpoint's ports.httpProtocolstring optionalThe protocol the HTTP port serves.
portsarray of integers optionalExample:
[80]The guest ports to declare, up to five. Must include
http_port. Defaults to only the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.environmentobject optionalExample:
{"APP_ENV": "production"}Environment variables passed into the MicroVM at boot, as key and value pairs. Not returned in responses.
tagsarray of strings optionalExample:
["example"]Tags to apply to the MicroVM.
Request Sample
Response Example
More Information
See /v2/microvms in the API reference for additional detail on responses, headers, parameters, and more.