How to Send Requests to a MicroVM

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

Each DigitalOcean MicroVM serves its container over authenticated HTTPS URLs. Every MicroVM gets a default URL for its HTTP port, and you can add URLs for its other ports. A request to a URL resumes a paused MicroVM when auto-resume is on.

Prerequisites

  • A running or paused MicroVM. See How to Create a MicroVM.
  • A token to authenticate requests, exported as the DIGITALOCEAN_TOKEN environment variable. Use one of the following:

Find the MicroVM’s URL

A MicroVM’s default URL has the following form:

https://<your-microvm-id>.<region>.microvm.ondigitalocean.com

You can find the hostname of the default URL in any of the following places:

  • Control Panel: Under Endpoint on the MicroVM’s Overview tab.
  • doctl: In the Endpoint column of doctl compute microvm get <your-microvm-id>, or in the output of doctl compute microvm url list <your-microvm-id>.
  • API: In the response’s urls array, in the entry with default set to true.

The hostname is empty, and the API entry’s status is PENDING, until provisioning finishes. The URL is ready when status is ACTIVE.

Send a Request

Send the request with your token in the Authorization header. This example requests the default page of a MicroVM running nginx in MKC1:

curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://<your-microvm-id>.mkc1.microvm.ondigitalocean.com"

If the MicroVM is paused and auto-resume is on, the request resumes it and waits until it is running. If auto-resume is off, the request fails until you resume the MicroVM.

The platform checks the token before the request reaches the MicroVM. It then removes the Authorization header and DigitalOcean’s own identity headers, so your application never receives the token or the caller’s account details. Your application receives the rest of the request’s headers, plus X-Forwarded-For, X-Forwarded-Proto, and X-Request-Id.

Add and Remove URLs

You can add a URL for any port you declared when you created the MicroVM, including a second URL for the HTTP port. Each URL has its own hostname. A MicroVM can have up to 10 URLs, including the default URL. You can add and remove URLs while the MicroVM is running or paused.

You need a personal access token with the microvm:update scope to add and remove URLs. Accounts in a free trial cannot add URLs. In doctl, the url commands need v2.0.1 or later.

Using the Control Panel

Go to the MicroVMs page, click the MicroVM’s name, then click the Settings tab. The Public URLs row lists the MicroVM’s URLs and shows how many it has out of the maximum.

To add a URL, click Add URL, choose the Port the URL routes to, then click Add URL. The new URL shows Pending until its hostname is assigned. You cannot change the port of an existing URL. To route to a different port, remove the URL and add a new one.

To remove a URL, click the trash icon next to it, then click Remove URL. Requests to that URL stop working immediately. The MicroVM’s other URLs are not affected.

Using doctl

Add a URL for a port. Without --port, the URL routes to the HTTP port.

How to Add an Ingress URL to a 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 url add. Basic usage looks like this, but you can read the usage docs for more details:
    doctl compute microvm url add <microvm-id> [flags]

List the MicroVM’s URLs with doctl compute microvm url list. The list includes each URL’s ID, hostname, port, and status.

Remove a URL. The command prompts for confirmation, and --force skips the prompt.

How to Remove an Ingress URL From a 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 url remove. Basic usage looks like this, but you can read the usage docs for more details:
    doctl compute microvm url remove <microvm-id> <url-id> [flags]

Using the API

Send a POST request to /v2/microvms/<your-microvm-id>/urls. port is optional and defaults to the HTTP port.

How to Add a URL to 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/{microvm_id}/urls.

Using cURL:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"port":8080}' \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/urls"

A successful request returns HTTP 201 with the details of the new URL: id, hostname, port, default, and status. The status is PENDING until its route is published, then ACTIVE. The request returns HTTP 400 if the port is not one of the MicroVM’s ports, the MicroVM is not running or paused, or the MicroVM already has 10 URLs.

To remove a URL, send a DELETE request to /v2/microvms/<your-microvm-id>/urls/<your-url-id>. A successful request returns HTTP 204.

What Happens When You Remove a URL

When you remove a URL, its hostname stops resolving and is never reused, so a new URL always gets a new hostname. You can also remove the default URL. A MicroVM with no URLs cannot receive requests, the same as a MicroVM created with ingress set to false. To make it reachable again, add a URL.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.