DigitalOcean API (unofficial showcase)
GET/v2/microvms/{microvm_id}/console

Open a console in a MicroVM

To open an interactive /bin/sh console in a MicroVM's workload container, open a WebSocket connection to wss://api.digitalocean.com/v2/microvms/{microvm_id}/console.

Send the API token in the Authorization header of the handshake. Browsers cannot set this header, so you cannot open the console from browser JavaScript. The image must include /bin/sh. A MicroVM can have four consoles open at a time. If the MicroVM is paused and auto-resume is on, opening a console resumes it.

3 parameters
microvm_idstringrequired
The unique ID of the MicroVM.
rowsintegeroptional
The initial number of terminal rows.
Default:24
colsintegeroptional
The initial number of terminal columns.
Default:80

7 status codes
101The connection is upgraded to a WebSocket. Binary frames from the client are terminal input, and text frames are resize messages such as `{"resize":{"rows":40,"cols":120}}`. Binary frames from the server are terminal output with `stdout` and `stderr` combined. Text frames from the server are control messages: `{"status":{"state":"resuming"}}` while a paused MicroVM resumes, `{"error":{"code":"...","message":"..."}}` when the console fails to connect or start (with `code` set to `dial_failed`, `start_failed`, or `agent_error`), and `{"exit":{"code":0}}` when the shell exits. The server sends a ping every 30 seconds. A console closes after 4 hours, or after 30 minutes with no input and no output. A message larger than 1 MiB closes the console with WebSocket code 1009.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403The token does not have the required scope, or your team has reached a limit.

One documented failure

  • PERMISSION_DENIED

    permission denied

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
404The MicroVM or checkpoint does not exist, or it belongs to another team.

One documented failure

  • NOT_FOUND

    MicroVM not found

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: The token does not have the required scope, or your team has reached a limit. A 404 is returned: The MicroVM or checkpoint does not exist, or it belongs to another team. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.