A background task’s CPU usage does not keep the MicroVM running. If the task runs longer than the idle timeout, the MicroVM can pause mid-task, and the task stops until the MicroVM resumes. To keep the task running, set a longer idle timeout, or send requests or commands to the MicroVM while the task runs. For the maximum idle timeout, see MicroVMs Limits.
How to Run Commands and Open a Console in a MicroVM
Last verified 16 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.
You can run a single command in a DigitalOcean MicroVM using doctl or the API, and open an interactive console using the Control Panel, doctl, or the API. The Droplet console does not connect to MicroVMs. Both run inside the MicroVM’s workload container, so they see the same filesystem, environment variables, and processes as your application.
Commands and consoles differ in the following ways:
| Aspect | Run a command | Console |
|---|---|---|
| What runs | The command you send | /bin/sh |
| Input | None. Standard input is closed. | Your keystrokes |
| Output | stdout and stderr as separate fields |
One terminal stream |
| Result | Exit code in the response | Exit code when the shell exits |
The console needs /bin/sh in your image. Minimal images without a shell support running commands but not the console.
If the MicroVM is paused and auto-resume is on, running a command or opening a console resumes it, and the command or console waits until the MicroVM is running. If auto-resume is off, resume the MicroVM first, or the request fails.
To copy files into or out of a MicroVM, see How to Upload and Download Files.
Prerequisites
- For
doctlor the API, a personal access token with themicrovm:updatescope. MicroVM access tokens do not work for commands or consoles. - For
doctl,doctlv1.181.0 or later. - Commands and consoles enabled for your team. Check that
exec_ptyis enabled in the features list ofdoctl compute microvm optionsorGET /v2/microvms/options. If it is not, requests return HTTP 403.
Open a Console Using the Control Panel
Go to the MicroVMs page, click the MicroVM’s name, then click the Console tab. The console is available when the MicroVM is running or paused. A paused MicroVM resumes when you open the console.
The console opens a shell in the MicroVM’s workload container. To end the session, type exit or press Ctrl+D.
Run a Command or Open a Console Using doctl
Run a command with doctl compute microvm exec. Put -- before the command so doctl does not read the command’s flags as its own:
doctl compute microvm exec <your-microvm-id> -- nginx -vdoctl prints the command’s output. If the command exits non-zero, doctl also exits non-zero and reports the command’s exit code. To set the working directory, add --cwd.
The command runs directly, not through a shell. To use pipes, redirects, &&, or environment variables, wrap the command in sh -c:
doctl compute microvm exec <your-microvm-id> -- sh -c 'ls /usr/share/nginx/html | wc -l'Open an interactive console with doctl compute microvm console. To leave the console, type exit or press Ctrl+D:
doctl compute microvm console <your-microvm-id>The console needs an interactive terminal. It does not work in scripts, CI jobs, or with piped input.
Run a Command Using the API
Send a POST request to /v2/microvms/<your-microvm-id>/exec with argv and an optional cwd. As with doctl, argv runs directly, not through a shell:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"argv": ["nginx", "-v"]}' \
"https://api.digitalocean.com/v2/microvms/<your-microvm-id>/exec"The response contains stdout, stderr, exit_code, and output_encoding, plus truncated when the output was cut off. By default, stdout and stderr are UTF-8 JSON strings, and bytes that are not valid UTF-8 are replaced. To get the exact bytes of binary output, set "output_encoding": "base64" in the request. The response then returns stdout and stderr as Base64.
HTTP 200 means the command ran, even if the command itself failed. Check exit_code for the command’s result. The endpoint returns the following other status codes:
| Status | Meaning |
|---|---|
| 400 | The request is malformed, argv is missing or empty, output_encoding is not utf-8 or base64, or the body is larger than 1 MiB. Also returned while the MicroVM is provisioning or its workload is not running. Retry when the MicroVM is running. |
| 401 | The token is missing or invalid. |
| 403 | The token does not have the microvm:update scope, or running commands is not available for your team. |
| 404 | The MicroVM does not exist, or it belongs to another team. |
| 429 | Too many requests with this token, or the service is busy. Retry after a short delay. |
| 502 | The command did not reach the workload. |
| 504 | The command did not finish within 40 seconds. |
Open a Console Using the API
The console is a WebSocket at wss://api.digitalocean.com/v2/microvms/<your-microvm-id>/console. Send your API token in the Authorization header of the handshake. Browsers cannot set this header, so you cannot open the console from browser JavaScript. Set the initial terminal size with the rows and cols query parameters. The default is 24 rows by 80 columns.
This example uses websocat. The -b flag sends input as binary frames, which the console requires:
websocat -b -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"wss://api.digitalocean.com/v2/microvms/<your-microvm-id>/console?rows=24&cols=80"The console uses the following WebSocket frames:
- Client to server, binary: Terminal input, such as keystrokes.
- Client to server, text: A resize, such as
{"resize":{"rows":40,"cols":120}}. Other text is sent to the shell as input. - Server to client, binary: Terminal output, with
stdoutandstderrcombined. - Server to client, text: A control message. Ignore keys you do not recognize. The control messages are:
{"status":{"state":"resuming"}}: The MicroVM was paused and is resuming. The shell starts when the MicroVM is running.{"status":{"state":"connected"}}: The shell started.{"status":{"state":"idle_warning"}}: The console has had no input for almost 30 minutes and closes in 2 minutes. Any input cancels the warning.{"error":{"code":"...","message":"..."}}: The console failed or closed.codeis one of the following:dial_failed,start_failed, oragent_error: The console failed to connect or start.idle_timeout: The console had no input for 30 minutes.session_max_duration: The console reached the 4-hour limit.client_unresponsive: The client stopped responding.
{"exit":{"code":0}}: The shell exited with this code. The server then closes the connection normally.
The server sends a WebSocket ping every 30 seconds. Your client must keep reading from the connection so its WebSocket library answers the pings. Most libraries answer pings automatically.
Before the upgrade to WebSocket, the console returns the same 400, 401, 403, and 404 errors as running a command. It returns HTTP 429 when the MicroVM already has four consoles open or the service is busy.
Run Longer Tasks
A command has 40 seconds to finish. To run a longer task, start it in the background with its output redirected, then check on it with later commands:
doctl compute microvm exec <your-microvm-id> -- sh -c 'nohup <your-long-task> > /tmp/task.log 2>&1 &'Redirect the output as shown. If a background process keeps the command’s output open, the command does not return until the 40-second limit.
You can also run a longer task in the console, which stays open for up to 4 hours. Output from the task does not keep the console open. If you send no input for 30 minutes, the console closes and its shell ends. Jobs started with nohup or with their output redirected keep running.
For other limits on commands and consoles, see MicroVMs Limits.