For AI agents: The documentation index is at 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).

You can run a single command or open an interactive console in a DigitalOcean MicroVM using doctl or the API. The Control Panel does not support either, and the Droplet console in the Control Panel 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:

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.

Prerequisites

• A personal access token with the microvm:update scope.
• For doctl, doctl v1.173.0 or later.

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 -v

doctl 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, and exit_code, plus truncated when the output was cut off. stdout and stderr are JSON strings, so bytes that are not valid UTF-8 are replaced. To return binary output, encode it in the command, for example with sh -c '<your-command> | 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:

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 stdout and stderr combined.
• 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.
  • {"error":{"code":"...","message":"..."}}: The console failed to connect or start. code is dial_failed, start_failed, or agent_error.
  • {"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 401, 403, and 404 errors as running a command, and HTTP 429 when the MicroVM already has four consoles open.

Run Longer Tasks

A command has 60 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 60-second limit.

You can also run a longer task in the console, which stays open for up to 4 hours.

For other limits on commands and consoles, see MicroVMs Limits.