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_TOKENenvironment variable. Use one of the following:- A personal access token with only the
microvm:accessscope. It can reach every MicroVM on your team. Use this token only for requests to MicroVMs. - An access token for the MicroVM, which can reach only that MicroVM.
- A personal access token with only the
Find the MicroVM’s URL
A MicroVM’s default URL has the following form:
https://<your-microvm-id>.<region>.microvm.ondigitalocean.comYou 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 ofdoctl compute microvm url list <your-microvm-id>. - API: In the response’s
urlsarray, in the entry withdefaultset totrue.
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.
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.
Using the API
Send a POST request to /v2/microvms/<your-microvm-id>/urls. port is optional and defaults to the HTTP port.
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.