---
title: dots.v2.microvms.post()
description: Create a MicroVM
product: Reference
url: https://docs.digitalocean.com/reference/dots/reference/microvms/microvms-create/
last_updated: "2026-11-13"
---

> **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).

# dots.v2.microvms.post()

Generated on 13 Nov 2026 from DoTs version [`v1.24.0`](https://github.com/digitalocean/dots/releases/tag/v1.24.0)

## Usage

```typescript
client.v2.microvms.post(body: Microvm_create, requestConfiguration?: RequestConfiguration<object>): Promise<undefined | MicrovmsPostResponse>
```

## Description

To create a MicroVM, send a POST request to [`/v2/microvms`](https://docs.digitalocean.com/reference/api/reference/microvms/index.html.md#microvms_create).

`name` and `source` are required. Set `source.oci_ref` to create the MicroVM from a `linux/amd64` container image, or `source.checkpoint_id` to create it from a checkpoint. With `oci_ref`, `region` and `size` are also required.

A MicroVM created from an image is returned with `state` set to `creating`. Poll `GET /v2/microvms/{microvm_id}` until `state` is `running`. A MicroVM created from a checkpoint is usually returned already `running`.

All settings are fixed at creation. There is no update endpoint.

## Parameters

`name` string required

Example: `example-microvm`

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

`source` object required

What the MicroVM runs. Set exactly one of `oci_ref` or `checkpoint_id`.

## Show child properties

`ociRef` string optional

Example: `docker.io/library/nginx:latest`

A reference to a `linux/amd64` container image in the form `registry/repository:tag`. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

`checkpointId` string optional

Example: `01a0ed98-0a74-75dd-a625-e4856adbc298`

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

`region` string optional

Example: `mkc1`

The slug of the region to create the MicroVM in. Required with `source.oci_ref`.

`size` object optional

The MicroVM's size. `cpu` and `memory` must be one of the pairs `1`/`2048`, `2`/`4096`, `8`/`16384`, or `16`/`32768`. The size sets the disk, which is returned in responses.

## Show child properties

`cpu` integer required

Example: `1`

The number of vCPUs.

`memory` integer required

Example: `2048`

The amount of memory, in MiB.

`disk` integer optional read-only

Example: `50`

The size of the disk, in GB. Set by the size.

`networking` string optional

`public` sends outbound traffic through a shared NAT gateway. `vpc` places the MicroVM in the VPC network set by `vpc_uuid`.

One of: `public`, `vpc`

Default: `public`

`vpcUuid` string optional

Example: `5a4981aa-9653-4bd1-bef5-d6bff52042e4`

The ID of a VPC network in the same region that belongs to your team. When `networking` is `vpc` and this is omitted, the team's default VPC is used.

`egressPolicy` object optional

An outbound allow list. A destination that matches any rule is allowed; `default_action` decides every other destination. Only valid with `public` networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected `HTTP_PROXY` / `HTTPS_PROXY` environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, exactly as supplied. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.

## Show child properties

`defaultAction` string optional

What to do with a destination no rule matches. `deny` refuses it (an HTTP request gets a 403 and a TLS connection is closed).

One of: `deny`, `allow`

Default: `deny`

`rules` array of objects optional

The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an `ip` rule. Each rule sets exactly one of `domain` or `ip`.

### Show child properties

`domain` string optional

Example: `api.example.com`

An exact host such as `api.example.com`, or a wildcard such as `*.example.com`.

`ip` string optional

Example: `203.0.113.5`

An exact IP address. CIDR ranges are not supported.

`projectId` string optional

Example: `4de7ac8b-495b-4884-9a69-1050c6793cd6`

The project to place the MicroVM in. Omit to use the team's default project. A project that does not belong to the team is rejected.

`ingress` boolean optional

Example: `true`

Whether to create the MicroVM with a default public URL. Defaults to `true`. Set to `false` to create the MicroVM without one; URLs can be added later with POST `/v2/microvms/{microvm_id}/urls`.

Default: `true`

`autoPause` object optional

Automatic pause settings. A MicroVM always pauses after it is idle for `idle_timeout`. Sending `enabled` set to `false` is rejected.

## Show child properties

`enabled` boolean optional

Example: `true`

Whether auto-pause is on. Always `true`.

`idleTimeout` string optional

Example: `5m0s`

How long the MicroVM is idle before it pauses, as a duration such as `30s`, `5m`, or `1h`. Defaults to `5m`. The maximum is `4h`. Responses show the duration in the form `5m0s`.

`autoResume` boolean optional

Example: `true`

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused. Set to `false` to require a manual resume.

Default: `true`

`httpPort` integer optional

Example: `80`

The guest port the workload serves HTTP on. Defaults to `8080`. Not returned in responses. When creating from a checkpoint without `ports`, must be one of the checkpoint's ports.

Default: `8080`

`httpProtocol` string optional

The protocol the HTTP port serves.

One of: `http`, `http2`

`ports` array of integers optional

Example: `[80]`

The guest ports to declare, up to five. Must include `http_port`. Defaults to only the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

`environment` object optional

Example: `{"APP_ENV": "production"}`

Environment variables passed into the MicroVM at boot, as key and value pairs. Not returned in responses.

`tags` array of strings optional

Example: `["example"]`

Tags to apply to the MicroVM.

## Request Sample

## Show Request Sample

```typescript
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary";
import {
    createDigitalOceanClient,
    DigitalOceanApiKeyAuthenticationProvider,
} from "@digitalocean/dots";

const authProvider = new DigitalOceanApiKeyAuthenticationProvider(process.env.DIGITALOCEAN_TOKEN!);
const adapter = new FetchRequestAdapter(authProvider);
const client = createDigitalOceanClient(adapter);

const response = await client.v2.microvms.post({
    name: "example-microvm",
    region: "mkc1",
    size: {
        cpu: 1,
        memory: 2048,
    },
    source: {
        ociRef: "docker.io/library/nginx:latest",
    },
    httpPort: 80,
    httpProtocol: "http",
    autoPause: {
        idleTimeout: "5m",
    },
    tags: [
        "example",
    ],
});
```

## Response Example

## Show Response Example

```json
{
  "microvm": {
    "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "name": "example-microvm",
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "memory": 2048,
      "disk": 50
    },
    "source": {
      "oci_ref": "docker.io/library/nginx:latest"
    },
    "state": "creating",
    "networking": "public",
    "auto_pause": {
      "enabled": true,
      "idle_timeout": "5m0s"
    },
    "auto_resume": true,
    "http_protocol": "http",
    "ports": [
      80
    ],
    "tags": [
      "example"
    ],
    "urls": [
      {
        "hostname": "",
        "port": 80,
        "default": true,
        "status": "PENDING"
      }
    ],
    "created_at": "2026-09-29T21:38:29Z"
  }
}
```

## More Information

See [`/v2/microvms`](https://docs.digitalocean.com/reference/api/reference/microvms/index.html.md#microvms_create) in the API reference for additional detail on responses, headers, parameters, and more.