Give Feedback

MicroVMs API and doctl Referencepublic

Last verified 9 Oct 2026

DigitalOcean MicroVMs are lightweight virtual machines that run a container image in an isolated kernel, pause automatically when idle, and resume on the next request with memory, files, and processes intact.

Copy page as Markdown View page as Markdown

DigitalOcean MicroVMs are managed through the /v2/microvms API endpoints and the doctl compute microvm commands. This page lists the fields of the MicroVM and checkpoint objects, each endpoint, and each doctl command with its flags.

API Conventions

The base path is https://api.digitalocean.com/v2/microvms. Responses wrap objects in microvm, microvms, checkpoint, or checkpoints.

List endpoints take page and per_page query parameters. The default page size is 25, and the maximum is 200. List responses include the standard links and meta pagination objects. Any request can return HTTP 429 when you exceed rate limits.

Errors return a JSON object with a code, such as NOT_FOUND, and a human-readable message.

MicroVM Object

All MicroVM fields are set at creation. There is no update endpoint.

Field	Type	Description
`id`	string	Unique ID. Read-only.
`name`	string	Required on create. Unique in the region. 1 to 63 lowercase letters, digits, and hyphens.
`region`	string	Required when `source.oci_ref` is set. When creating from a checkpoint, omit it to use the checkpoint’s region.
`size`	object	`cpu` is the number of vCPUs, and `memory` is in MiB. Required with `oci_ref`. Must be one of the pairs `1`/`2048`, `2`/`4096`, `8`/`16384`, or `16`/`32768`. Responses also include `disk`, in GB. When creating from a checkpoint, a different size is rejected.
`source`	object	Required on create. Contains either `oci_ref` (string), a container image reference, or `checkpoint_id` (string).
`state`	string	Read-only. One of the states in MicroVM Lifecycle.
`failure_reason`	string	Read-only. Why the MicroVM failed. Present only when `state` is `failed`.
`networking`	string	`public` (default) or `vpc`.
`vpc_uuid`	string	Required when `networking` is `vpc`.
`auto_pause`	object	`idle_timeout` is a duration such as `30s`, `5m`, or `1h`, with a default of `5m` and a maximum of `4h`. Responses show the duration in the form `5m0s`, and `enabled` is always `true`. Sending `enabled` set to `false` is rejected.
`auto_resume`	boolean	Whether incoming traffic resumes a paused MicroVM. Defaults to `true`.
`http_port`	integer	Create only. The port the workload serves HTTP on. Defaults to `8080`. Not returned in responses. The `urls` entry with `default` set to `true` shows the HTTP port.
`http_protocol`	string	`http` or `http2`.
`ports`	array of integers	Up to five ports, including `http_port`. Defaults to the HTTP port. Only the HTTP port is reachable through the endpoint during the public preview.
`environment`	object	Create only. Key and value pairs passed into the MicroVM at boot. Not returned in responses.
`tags`	array of strings	Tags to apply.
`urls`	array of objects	Read-only. The MicroVM’s endpoints. Each entry has `hostname`, `port`, `default`, and `status`. `hostname` is empty and `status` is `PENDING` until provisioning finishes, then `status` is `ACTIVE`.
`created_at`	string	Read-only. When the MicroVM was created, in ISO 8601 format.

Checkpoint Object

Field	Type	Description
`id`	string	Unique ID.
`name`	string	The name you gave the checkpoint, or a generated name such as `checkpoint-20260929-143559`.
`microvm_id`	string	The ID of the MicroVM the checkpoint was taken from.
`microvm_name`	string	The name of the MicroVM the checkpoint was taken from.
`region`	string	The checkpoint’s region.
`size`	object	The size the checkpoint was taken at, with `cpu`, `memory` in MiB, and `disk` in GB. A MicroVM created from the checkpoint uses this size.
`status`	string	One of the statuses in MicroVM Checkpoints.
`memory_bytes`	integer	Stored size of the checkpoint’s memory.
`disk_bytes`	integer	Stored size of the checkpoint’s disk.
`created_at`	string	When the checkpoint was created, in ISO 8601 format.

Options Object

GET /v2/microvms/options returns the following fields:

Field	Type	Description
`default_region`	string	The region MicroVMs are created in by default, such as `mkc1`.
`sizes`	array of objects	The sizes available to your team. Each entry has `cpu`, `memory` in MiB, `disk` in GB, `regions`, `available`, and `pricing` with `price_per_hour` and `price_per_month`.
`resource_pricing`	object	Per-resource rates: `price_per_vcpu_hour`, `price_per_gib_memory_hour`, `price_per_gib_storage_month`, and `price_per_gib_bandwidth`.
`account_limits`	object	Your team’s limits: `max_total_count` (MicroVMs, running and paused), `max_memory_bytes`, `max_disk_bytes`, and `max_idle_timeout_seconds`.
`features`	array of objects	Features enabled for your team. Each entry has `name` and `enabled`.

API Endpoints

Method	Path	Description
`GET`	`/v2/microvms`	List MicroVMs. The `region`, `name` (exact match), and `tag_name` filters combine with AND.
`POST`	`/v2/microvms`	Create a MicroVM. Returns HTTP 201.
`GET`	`/v2/microvms/<your-microvm-id>`	Get a MicroVM.
`DELETE`	`/v2/microvms/<your-microvm-id>`	Delete a MicroVM. Returns HTTP 204.
`POST`	`/v2/microvms/<your-microvm-id>/pause`	Pause a MicroVM.
`POST`	`/v2/microvms/<your-microvm-id>/resume`	Resume a MicroVM.
`POST`	`/v2/microvms/<your-microvm-id>/exec`	Run a command. Body contains `argv` and an optional `cwd`.
`GET`	`/v2/microvms/<your-microvm-id>/console`	Open a WebSocket console. Query parameters `rows` and `cols`.
`POST`	`/v2/microvms/<your-microvm-id>/checkpoints`	Start a checkpoint. Optional body `name`.
`GET`	`/v2/microvms/checkpoints`	List checkpoints, newest first. Filter with `microvm_id`.
`GET`	`/v2/microvms/checkpoints/<your-checkpoint-id>`	Get a checkpoint.
`DELETE`	`/v2/microvms/checkpoints/<your-checkpoint-id>`	Delete a checkpoint. Returns HTTP 400 while the checkpoint is still being captured.
`GET`	`/v2/microvms/options`	Get the default region, sizes, and account limits available to your team.

doctl Commands

The following commands are under doctl compute microvm in doctl v1.173.0 and later. Command aliases are in parentheses.

Command	Description
`list` (`ls`)	List MicroVMs.
`get <id>` (`g`)	Show a MicroVM, including its state and endpoint.
`create <name>` (`c`)	Create a MicroVM.
`pause <id>`	Pause a running MicroVM.
`resume <id>`	Resume a paused MicroVM.
`delete <id>...` (`d`, `rm`)	Delete one or more MicroVMs. Prompts for confirmation unless you pass `--force` (`-f`).
`options`	List the sizes, default region, and account limits available to your team.
`exec <id> -- <command>`	Run a command in the MicroVM and print its output. If the command exits non-zero, `doctl` also exits non-zero. `--cwd` sets the working directory.
`console <id>`	Open an interactive terminal in the MicroVM.
`checkpoint list` (`ls`)	List checkpoints, newest first. `--microvm-id` filters to one MicroVM’s checkpoints.
`checkpoint get <id>` (`g`)	Show a checkpoint, including its status.
`checkpoint create <microvm-id>` (`c`)	Start a checkpoint of a MicroVM. `--name` sets an optional name.
`checkpoint delete <id>...` (`d`, `rm`)	Delete one or more checkpoints. Prompts for confirmation unless you pass `--force` (`-f`).

The checkpoint command also has the aliases checkpoints and cp.

Flags for `doctl compute microvm list`

The list filters combine with AND:

--region: Only MicroVMs in this region, such as mkc1.
--name: Only the MicroVM with this exact name.
--tag-name: Only MicroVMs with this tag. A tag that matches nothing returns an empty list.

Flags for `doctl compute microvm create`

Set exactly one source:

--oci-ref: The container image to run, such as docker.io/library/nginx:latest.
--checkpoint-id: The ID of a checkpoint to create the MicroVM from.

The following flags are required with --oci-ref, and inherited from the checkpoint with --checkpoint-id:

--region: The region to create the MicroVM in, such as mkc1.
--cpu: The number of vCPUs.
--memory: The memory in MiB. Must match --cpu as listed in Sizes.

The following flags are optional:

--networking: public (default) or vpc.
--vpc-uuid: The ID of the VPC network to place the MicroVM in. Only valid with --networking vpc.
--auto-pause-idle-timeout: How long the MicroVM is idle before it pauses, such as 30s, 5m, or 1h. Defaults to 5m, with a maximum of 4h.
--auto-resume: Whether incoming traffic resumes a paused MicroVM. Defaults to true. Pass --auto-resume=false to require a manual resume.
--http-port: The port your workload serves HTTP on. Defaults to 8080.
--http-protocol: http or http2.
--ports: A guest port to declare, up to five. Repeatable. Must include the HTTP port. Defaults to only the HTTP port. Only the HTTP port is reachable during the public preview.
--env: An environment variable in KEY=VALUE form. Repeatable.
--tag: A tag to apply. Repeatable.