DigitalOcean API (unofficial showcase)
POST/v2/microvms/{microvm_id}/exec

Run a command in a MicroVM

To run a command in a MicroVM's workload container, send a POST request to /v2/microvms/{microvm_id}/exec.

argv runs directly, not through a shell, with standard input closed. If the MicroVM is paused and auto-resume is on, the request resumes it and waits until it is running.

A command has 60 seconds to finish. Your team can run 32 commands at once and 60 commands per minute. Rejected requests count toward the per-minute limit.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
microvm_idstringrequired
The unique ID of the MicroVM.
argvarray<string>required
The command and its arguments.
cwdstringoptional
The working directory to run the command in.

9 status codes
200The command ran. HTTP 200 is returned even when the command itself fails. Check `exit_code` for the command's result.
stdoutstringoptional
The command's standard output. Bytes that are not valid UTF-8 are replaced.
stderrstringoptional
The command's standard error. Bytes that are not valid UTF-8 are replaced.
exit_codeintegeroptional
The command's exit code.
truncatedbooleanoptional
Present and `true` when the output exceeded 4 MiB and was cut off.
400The request was malformed, failed validation, or is not allowed in the resource's current state.

3 documented failures

  • INVALID_SIZE

    no supported size matches the requested resources: 3 vCPU with 2048 MiB of memory (supported: 1vCPU/2048MiB, 2vCPU/4096MiB, 8vCPU/16384MiB, 16vCPU/32768MiB)

  • INVALID_AUTO_PAUSE

    auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum

  • FAILED_PRECONDITION

    checkpoint 01a11cd5-25dd-790f-a77c-3677f24bca85 is still being captured; retry delete once the capture completes

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
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.
502The command did not reach the workload, for example because the container is not running.

One documented failure

  • UNAVAILABLE

    workload unavailable

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
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 400 is returned: The request was malformed, failed validation, or is not allowed in the resource's current state. 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. A 502 is returned: The command did not reach the workload, for example because the container is not running. Any other status is an error: There was an unexpected error.