dots.v2.microvms.post()

Generated on 13 Nov 2026 from DoTs version v1.24.0

Usage

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.

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
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
{
  "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 in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.