---
title: How to Create a MicroVM (public)
description: Create a MicroVM from a container image using the Control Panel, doctl, or the API.
product: Microvms
url: https://docs.digitalocean.com/products/microvms/how-to/create/
last_updated: "2026-10-09"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](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).

# How to Create a MicroVM (public)

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 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](https://docs.digitalocean.com/products/microvms/how-to/checkpoint/index.html.md).

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)](https://docs.digitalocean.com/products/container-registry/index.html.md).
- For VPC networking, a [VPC network](https://docs.digitalocean.com/products/networking/vpc/how-to/create/index.html.md) in MKC1 that belongs to your team.
- For `doctl` or the API, a [personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with the `microvm:create` and `microvm:read` scopes. The `doctl` examples need [`doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md) v1.173.0 or later.

## Create a MicroVM Using the Control Panel

Go to the [**MicroVMs** page](https://cloud.digitalocean.com/microvms), 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](https://docs.digitalocean.com/products/microvms/details/limits/index.html.md#sizes). 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](https://docs.digitalocean.com/products/microvms/details/limits/index.html.md#sizes).

```shell
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:

```shell
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:

```shell
doctl compute microvm get <your-microvm-id>
```

To list the sizes, default region, and account limits available to your team, run:

```shell
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](https://docs.digitalocean.com/products/microvms/details/limits/index.html.md#sizes).

```shell
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](https://docs.digitalocean.com/products/microvms/reference/endpoints-and-commands/index.html.md#microvm-object).

Poll the MicroVM until `state` is `running`:

```shell
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`.