For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

A DigitalOcean MicroVM runs one container image in its own lightweight virtual machine. You set every MicroVM setting at creation, and you cannot change the image, size, idle timeout, environment variables, tags, ports, networking, region, or auto-resume afterward.

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 container image built for linux/amd64. 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.
• For doctl or the API, a personal access token with the microvm:create and microvm:read scopes. The doctl examples need doctl v1.173.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. Enter an image reference in the form registry/repository:tag, such as docker.io/library/nginx:latest, and then click Import. For a private image, push it to DOCR first, then enter its DOCR reference.

When the import finishes, the image appears in your list with a Public or DOCR label, and you can reuse it for later MicroVMs. Imported images exist only in the Control Panel. The API and doctl take an image reference directly. To remove an imported image, click Delete image.

Choose a Region and Size

Under Choose a region, select MKC1.

Under Choose a size, move the CPU slider to select a size. The summary lists the vCPUs, memory, and disk for the size. 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

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.

Set the HTTP Port, Environment Variables, and Idle Timeout

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, then fill in Key and Value.

Set Idle timeout to a duration such as 30s, 5m, or 1h. The default is 5m, and the maximum is 4h. Auto-pause and auto-resume are on. To turn auto-resume off, create the MicroVM with doctl or the API.

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 in the region.

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.

doctl compute microvm create example-microvm \
  --oci-ref docker.io/library/nginx:latest \
  --region mkc1 \
  --cpu 1 \
  --memory 2048 \
  --http-port 80 \
  --http-protocol http \
  --tag example

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:

• --auto-pause-idle-timeout: How long the MicroVM is idle before it pauses, such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 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 and --vpc-uuid <your-vpc-uuid>: Places the MicroVM in a VPC network in MKC1.

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

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, replacing <your-microvm-id> with the MicroVM’s ID:

doctl compute microvm get <your-microvm-id>

To list the sizes, default region, 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.

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. For all request fields, see MicroVMs API and doctl Reference.

Poll the MicroVM until state is running:

curl -X GET \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/<your-microvm-id>"

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