MicroVMs API and doctl Reference
Last verified 17 Nov 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.
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, checkpoints, url, access_token, or access_tokens.
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
To change a MicroVM’s name, tags, or auto_pause.idle_timeout, send a PATCH request. All other fields are fixed at creation. To move a MicroVM to another project, use the Projects API. To add or remove URLs, use the URL endpoints.
| Field | Type | Description |
|---|---|---|
id |
string | Unique ID. Read-only. |
name |
string | Required on create. Unique among your team’s MicroVMs 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 GiB. 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). Responses for a MicroVM created from a checkpoint include both. |
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 | Create only. The VPC network to use with networking set to vpc. Defaults to your team’s default VPC network in the region. |
egress_policy |
object | Create only, with public networking. The outbound policy, with default_action, rules, and credentials. Responses omit credential secrets. See How to Restrict a MicroVM’s Outbound Traffic. |
auto_pause |
object | idle_timeout is a duration such as 30s, 5m, or 1h, with a default of 5m. The maximum is your team’s max_idle_timeout_seconds. 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. To reach a port other than the HTTP port, add a URL for it. |
ingress |
boolean | Create only. Set to false to create the MicroVM without a default URL. Defaults to true. |
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. |
project_id |
string | Create only. The project to place the MicroVM in. Defaults to your team’s default project. |
insights_enablement |
object | Create only. Boolean fields metrics, logs, and traces for which telemetry Insights stores. Metrics default to true, and logs and traces to false. |
urls |
array of objects | Read-only. The MicroVM’s URLs. Each entry has id, hostname, port, default, and status. hostname is empty and status is PENDING until the URL is published, 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 GiB. A MicroVM created from the checkpoint uses this size. |
status |
string | One of the statuses in MicroVM Checkpoints. |
failure_reason |
string | Why the capture failed. Present only when status is CHECKPOINT_FAILED. |
egress_policy |
object | The outbound policy that MicroVMs created from the checkpoint inherit. Omitted when there is none. |
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. |
Access Token Object
| Field | Type | Description |
|---|---|---|
id |
string | Unique ID. Use it to revoke the token. |
name |
string | Required on create. 1 to 64 characters, unique among the MicroVM’s active tokens. |
expires_in_seconds |
integer | Create only. How long the token is valid. Omit it for a token that does not expire. |
created_at |
string | When the token was created, in ISO 8601 format. |
expires_at |
string | When the token expires, in ISO 8601 format. Omitted for a token that does not expire. |
token |
string | The token value. Returned only in the create response. |
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 GiB, 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. max_concurrent_running is deprecated. |
features |
array of objects | Features enabled for your team. Each entry has name and enabled. Names include exec_pty for commands and the console, file_transfer, egress_policy, and egress_credentials. |
API Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/v2/microvms |
List MicroVMs. The region, name, and tag_name filters combine with AND. name is a case-insensitive substring match. |
POST |
/v2/microvms |
Create a MicroVM. Returns HTTP 201. |
GET |
/v2/microvms/<your-microvm-id> |
Get a MicroVM. |
PATCH |
/v2/microvms/<your-microvm-id> |
Update a MicroVM’s name, tags, or auto_pause.idle_timeout. tags replaces the current set. Returns HTTP 200. |
DELETE |
/v2/microvms/<your-microvm-id> |
Delete a MicroVM. Returns HTTP 204, or HTTP 400 while the MicroVM is being created or a checkpoint of it is being captured. |
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>/urls |
Add a URL. Optional body port. Returns HTTP 201. |
DELETE |
/v2/microvms/<your-microvm-id>/urls/<your-url-id> |
Remove a URL. Returns HTTP 204. |
POST |
/v2/microvms/<your-microvm-id>/access_tokens |
Create an access token. Body contains name and an optional expires_in_seconds. Returns HTTP 201. |
GET |
/v2/microvms/<your-microvm-id>/access_tokens |
List active access tokens, oldest first. |
DELETE |
/v2/microvms/<your-microvm-id>/access_tokens/<your-token-id> |
Revoke an access token. Returns HTTP 204. |
POST |
/v2/microvms/<your-microvm-id>/exec |
Run a command. Body contains argv, an optional cwd, and an optional output_encoding of utf-8 or base64. |
GET |
/v2/microvms/<your-microvm-id>/console |
Open a WebSocket console. Query parameters rows and cols. |
PUT |
/v2/microvms/<your-microvm-id>/files |
Upload a file. Query parameters path, mode, uid, gid, and sha256. The body is the raw file. |
GET |
/v2/microvms/<your-microvm-id>/files |
Download a file. Query parameter path. |
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, features, and account limits available to your team. |
doctl Commands
The following commands are under doctl compute microvm. Command aliases are in parentheses. Some commands need a newer version of doctl, as noted.
| Command | Description |
|---|---|
list (ls) |
List MicroVMs. |
get <id> (g) |
Show a MicroVM, including its state and default URL. |
create <name> (c) |
Create a MicroVM. |
update <id> (u) |
Update a MicroVM’s name, tags, or auto-pause idle timeout. --name, --tag, --clear-tags, and --auto-pause-idle-timeout set the values. Set at least one flag. Requires v2.6.0 or later. |
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, features, 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. |
upload <id> |
Upload a file. Requires --local-file and --path. --mode, --uid, and --gid are optional. Requires v2.0.1 or later. |
download <id> |
Download a file. Requires --path and --save-to. Requires v2.0.1 or later. |
url list <id> (ls) |
List a MicroVM’s URLs. Requires v2.0.1 or later. |
url add <id> (a) |
Add a URL. --port sets the port, and defaults to the HTTP port. Requires v2.0.1 or later. |
url remove <id> <url-id> (rm) |
Remove a URL. Prompts for confirmation unless you pass --force (-f). Requires v2.0.1 or later. |
access-token create <id> (c) |
Create an access token. Requires --name. --expires-in-seconds is optional. Requires v2.3.0 or later. |
access-token list <id> (ls) |
List a MicroVM’s active access tokens. Requires v2.3.0 or later. |
access-token revoke <id> <token-id> (rm, delete) |
Revoke an access token. Prompts for confirmation unless you pass --force (-f). Requires v2.3.0 or later. |
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. The url command has the alias urls, and access-token has the alias access-tokens.
Flags for doctl compute microvm list
The list filters combine with AND:
--region: Only MicroVMs in this region, such asmkc1.--name: Only MicroVMs whose name contains this value, ignoring case.--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 asdocker.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 asmkc1.--cpu: The number of vCPUs.--memory: The memory in MiB. Must match--cpuas listed in Sizes.
The following flags are optional:
--networking:public(default) orvpc.--vpc-uuid: The ID of the VPC network to place the MicroVM in. Only valid with--networking vpc. Defaults to your team’s default VPC network in the region.--auto-pause-idle-timeout: How long the MicroVM is idle before it pauses, such as30s,5m, or1h. Defaults to5m.--auto-resume: Whether incoming traffic resumes a paused MicroVM. Defaults totrue. Pass--auto-resume=falseto require a manual resume.--http-port: The port your workload serves HTTP on. Defaults to8080.--http-protocol:httporhttp2.--ports: A guest port to declare, up to five. Repeatable. Must include the HTTP port. Defaults to only the HTTP port.--env: An environment variable inKEY=VALUEform. Repeatable.--tag: A tag to apply. Repeatable.--ingress: Whether to create a default URL. Defaults totrue. Pass--ingress=falseto create the MicroVM without one. Requires v2.0.1 or later.--egress-allow: A destination the MicroVM may connect to: an exact hostname, a wildcard such as*.example.com, or an IPv4 address. Repeatable. Setting it restricts outbound traffic. Requires v2.1.0 or later.--egress-default-action:deny(default) orallow, for destinations that no--egress-allowrule matches. Requires v2.1.0 or later.