How to Create a MicroVM

Last verified 19 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.

A DigitalOcean MicroVM runs one container image in its own lightweight virtual machine. You choose most of a MicroVM’s settings at creation. After creation, you can change only its name, tags, idle timeout, project, URLs, and which telemetry Insights stores. For details, see How to Update a MicroVM.

This page covers creating a MicroVM from a container image. To create a MicroVM from a checkpoint, see How to Checkpoint a MicroVM.

The examples use docker.io/library/nginx:latest, which serves HTTP on port 80.

Prerequisites

  • A linux/amd64 container image in the Open Container Initiative (OCI) image format. MicroVMs do not support Docker-in-Docker images. You can use a public image, such as one from Docker Hub, or a private image in your team’s DigitalOcean Container Registry (DOCR).
  • For VPC networking, a VPC network in MKC1 that belongs to your team. If you do not choose one, the MicroVM uses your team’s default VPC network in the region.
  • For doctl or the API, a personal access token with the microvm:create and microvm:read scopes. The doctl examples need doctl v2.1.0 or later.

Create a MicroVM Using the Control Panel

Go to the MicroVMs page, then click Create MicroVM.

Choose an Image

Under Choose an image, open Container image. In Container image reference, enter an image reference in the form registry/repository:tag, such as docker.io/library/nginx:latest. For a private image, push it to DOCR first, then enter its DOCR reference. If you leave out the tag, the MicroVM uses latest, which can point to a different image each time you create a MicroVM.

The image is pulled while the MicroVM boots. If the image cannot be pulled, the MicroVM fails to start. References you used recently appear under Recent.

Choose a Region and Size

Under Choose a region, select MKC1.

Under Choose a size, move the CPU slider to select a size. Memory and disk scale with the number of vCPUs. For the available sizes, see MicroVMs Limits. A size that is not available on your plan is marked Not available on your current plan.

Choose Networking and Outbound Access

Under Networking, select one of the following:

  • Public: Outbound internet access through a shared NAT gateway.
  • VPC: Private access through a VPC network. Select a VPC network in MKC1.

With Public networking, you can limit where the MicroVM can connect. Under Outbound network (egress), turn on Restrict outbound traffic, then add the destinations to allow, such as api.example.com, *.example.com, or an IPv4 address. Everything not listed is blocked. You can also attach credentials, such as API keys, that the platform adds to requests to an allowed host. You cannot change the rules or credentials after creation. For how restricted outbound traffic works and how to attach credentials to allowed destinations, see How to Restrict a MicroVM’s Outbound Traffic.

Set Incoming Traffic and Environment Variables

Under Incoming traffic, set Port to the port your container listens on. For nginx, set it to 80. The default is 8080 in the Control Panel, the API, and doctl. Choose HTTP or HTTP/2 for Protocol.

To add environment variables, click Add variable under Environment variables, then fill in Key and Value.

However you set them, environment variable values are not baked into the container image. The platform stores them encrypted in DigitalOcean’s secrets store, keeps only a reference with the MicroVM, and passes the values to the container when it starts. The API and doctl never return the values after creation.

Set Auto-Pause and Auto-Resume

Under Auto-pause, set Idle timeout. Choose a preset or Custom, then enter a duration and unit. The default is 5 minutes. The maximum depends on your plan and is shown under the field.

Under Auto-resume, Auto-resume on traffic is on by default. Turn it off to keep a paused MicroVM paused until you resume it yourself.

Choose Insights Telemetry

Under Insights, metrics are always collected. To also store the MicroVM’s lifecycle logs and traces in DigitalOcean Insights, turn on Platform logs, Platform traces, or both. Logs and traces count toward your Insights ingestion usage. For what each signal contains, see How to Monitor a MicroVM.

Name and Create the MicroVM

Under Name your MicroVM, keep the suggested name or enter your own. Names can contain 1 to 63 lowercase letters, numbers, and hyphens, and must be unique among your team’s MicroVMs in the region.

Select the project for the MicroVM. If you do not choose one, the MicroVM goes in your team’s default project. To add tags, type a tag in Tags and press Enter.

Click Create MicroVM. The MicroVM’s details page opens with the MicroVM in the Creating state. When it is running, its URL appears under Endpoint.

Create a MicroVM Using doctl

Use doctl compute microvm create with --oci-ref to create a MicroVM from a container image. With --oci-ref, you must also set --region, --cpu, and --memory. --memory is in MiB and must match --cpu as listed in Sizes.

How to Create a New MicroVM Using the DigitalOcean CLI
  1. Install doctl, the official DigitalOcean CLI.
  2. Create a personal access token and save it for use with doctl.
  3. Use the token to grant doctl access to your DigitalOcean account.
    doctl auth init
  4. Finally, run doctl compute microvm create. Basic usage looks like this, but you can read the usage docs for more details:
    doctl compute microvm create <microvm-name> [flags]

The command prints the new MicroVM’s ID, state, and other details. The state is creating and the endpoint is empty until provisioning finishes.

The following optional flags configure the MicroVM:

  • --http-port: The port your container listens on. Defaults to 8080.
  • --http-protocol: The protocol for the HTTP port, http or http2.
  • --tag: A tag to apply to the MicroVM. Repeat the flag for each tag.
  • --checkpoint-id: Creates the MicroVM from a checkpoint instead of a container image. Use it in place of --oci-ref. With it, --region, --cpu, and --memory are optional.
  • --auto-pause-idle-timeout: How long the MicroVM is idle before it pauses, such as 30s, 5m, or 1h. Defaults to 5m. The maximum depends on your account and is between 1h and 4h.
  • --auto-resume=false: Keeps a paused MicroVM paused until you resume it manually.
  • --env: An environment variable in KEY=VALUE form. Repeat the flag for each variable.
  • --networking vpc: Places the MicroVM in your team’s default VPC network in the region. Add --vpc-uuid <your-vpc-uuid> to use a different VPC network.
  • --ports: A guest port to open for ingress, up to five including the HTTP port. Repeat the flag for each port. To reach a port other than the HTTP port, add a URL for it.
  • --egress-allow and --egress-default-action: Restricts outbound traffic. See How to Restrict a MicroVM’s Outbound Traffic.
  • --ingress=false: Creates the MicroVM without a default URL.

doctl help text lists an --auto-pause flag, but you cannot turn auto-pause off. Passing --auto-pause=false returns an API error.

To choose a project or store Insights logs and traces, use the Control Panel or the API. A MicroVM created with doctl goes in your team’s default project and stores metrics only.

For example, the following command creates a MicroVM with an environment variable in a VPC network:

doctl compute microvm create example-microvm \
  --oci-ref docker.io/library/nginx:latest \
  --region mkc1 \
  --cpu 1 \
  --memory 2048 \
  --http-port 80 \
  --env APP_ENV=production \
  --networking vpc \
  --vpc-uuid <your-vpc-uuid>

Check the MicroVM’s state with doctl compute microvm get. To list the sizes, default region, features, and account limits available to your team, run doctl compute microvm options.

Create a MicroVM Using the API

Send a POST request to /v2/microvms. name and source are required. source contains either oci_ref or checkpoint_id. With oci_ref, region and size are also required. size.memory is in MiB, and size must be one of the pairs listed in Sizes.

How to Create a MicroVM Using the DigitalOcean API

Create a personal access token and save it for use with the API.

cURL

Send a POST request to https://api.digitalocean.com/v2/microvms.

Using cURL:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "example-microvm", "region": "mkc1", "size": {"cpu": 1, "memory": 2048}, "source": {"oci_ref": "docker.io/library/nginx:latest"}, "http_port": 80, "http_protocol": "http", "auto_pause": {"idle_timeout": "5m"}, "tags": ["example"]}' \
  "https://api.digitalocean.com/v2/microvms"

A successful request returns HTTP 201 and a microvm object with state set to creating. Sending auto_pause.enabled set to false returns an error.

The request also accepts the following optional fields:

  • http_port: The port your container listens on. Defaults to 8080.
  • http_protocol: The protocol for the HTTP port, http or http2.
  • tags: Tags to apply to the MicroVM.
  • auto_pause.idle_timeout: How long the MicroVM is idle before it pauses, such as 30s, 5m, or 1h. Defaults to 5m. The maximum depends on your account and is between 1h and 4h.
  • project_id: The project to place the MicroVM in. Omit it to use your team’s default project.
  • insights_enablement: Whether Insights stores the MicroVM’s metrics, logs, and traces. Metrics are stored by default. Logs and traces are not.
  • egress_policy: An outbound allow list, and optionally credentials the platform adds to outbound requests. See How to Restrict a MicroVM’s Outbound Traffic.
  • ingress: Set to false to create the MicroVM without a default URL.

For all request fields, see MicroVMs API and doctl Reference.

Poll the MicroVM with a GET request to /v2/microvms/<your-microvm-id> until state is running.

To see the sizes, default region, features, and account limits available to your team, send a GET request to /v2/microvms/options.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.