Executing commands in the guest OS

POST /v2.1/servers/{server_id}/guest-agent/commands

Execute a command inside the guest operating system.

The exec command supports limited stdin, stdout, and stderr. The maximum combined size of captured output (stdout + stderr) is 100 KB. Output exceeding this limit may be truncated.

Request

Parameters

Name	In	Type	Description
`server_id`	path	string	The UUID of the server.
`command`	body	object	The command object.
`type`	body	string	Command type. Must be `exec`.
`arguments`	body	object	Command arguments.
`command`	body	array	Array of strings representing executable and arguments.

Example

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...> -d '{
  "command": {
    "type": "exec",
    "arguments": {
      "command": ["cmd.exe", "/c", "echo", "Hello", ">", "C:\\file.txt"]
    }
  }
}' https://<node_IP_addr>:8774/v2.1/servers/<server_id>/guest-agent/commands

Response

Parameters

Name	In	Type	Description
`command`	body	object	The command object.
`uuid`	body	string	The UUID of the command.
`type`	body	string	Command type (`exec`, `file-read`, `file-write`).
`instance_uuid`	body	string	The UUID of the server.
`status`	body	string	Command execution status at the API level.
`created_at`	body	string	The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In this example, the offset value is `-05:00`.
`updated_at`	body	string	The date and time when the resource was updated. If the resource has not been updated, this field will be `null`. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In this example, the offset value is `-05:00`.
`error`	body	string	Error description if the command failed. If the command succeeded, this field will be `null`.
`result`	body	object	Command execution result. The result is `null` in the following cases: The command has not yet completed (status: `PENDING`). The command failed before execution started. The command type does not return structured result data.

Status codes

Success

Code	Reason
`200 - OK`	Request was successful.

Error

Code	Reason
`400 - Bad Request`	Some content in the request was invalid.
`401 - Unauthorized`	User must authenticate before making a request.
`403 - Forbidden`	Policy does not allow current user to do this operation.
`404 - Not Found`	The requested resource could not be found.
`409 - Conflict`	This operation conflicted with another operation on this resource.

Example

{
  "command": {
    "created_at": "2026-03-09T12:13:22Z",
    "updated_at": null,
    "uuid": "3deced6f-3349-4121-ab46-a4d5c8ac5601",
    "type": "exec",
    "instance_uuid": "5a124ea0-36a0-49b8-9bd0-e937d958ca8f",
    "status": "PENDING",
    "error": null,
    "result": {}
  }
}