Running guest OS commands using vinfra

You can execute commands and transfer files inside virtual machines using the vinfra command-line tool.

Limitations

• Only system administrators with the guest_exec role can use these commands.
• The command record is retained only for a limited time (approximately 5–10 minutes) and is automatically deleted afterwards.
• The maximum combined size of stdout and stderr for the exec command is 100 KB. Output exceeding this limit may be truncated.

Prerequisites

• The VM must be in a running state.
• Virtual machines have the guest tools installed, as instructed in Installing guest tools.

To execute a command inside a virtual machine

Use the following command:

vinfra service compute server command exec <server> <command> [args...] [--input-data <input_data>]

<server>

VM ID or name

<command> [args...]

Command to execute (all remaining arguments are passed as-is)

--input-data <input_data>

Literal input data (if omitted, stdin is used)

Linux example. To create the file file.txt inside the virtual machine vm1, run:

# vinfra service compute server command exec vm1 /bin/sh -c "echo Hello > /tmp/file.txt"

Windows example. To create the file file.txt inside the virtual machine vm1, run:

# vinfra service compute server command exec vm1 cmd.exe /c "echo Hello > C:\file.txt"

You can check the status of your command in the vinfra service compute server command show output:

# vinfra service compute server command list vm1
+--------------------------------------+----------------------+------+---------+
| uuid                                 | created_at           | type | status  |
+--------------------------------------+----------------------+------+---------+
| 9f1a1fa2-561f-4281-abe9-331a2a96cb90 | 2026-03-09T16:16:13Z | exec | SUCCESS |
| bc57dbec-38cd-43b8-94f4-0e247c3bbaa9 | 2026-03-09T16:18:16Z | exec | SUCCESS |
+--------------------------------------+----------------------+------+---------+
# vinfra service compute server command show vm1 bc57dbec-38cd-43b8-94f4-0e247c3bbaa9
+---------------+--------------------------------------+
| Field         | Value                                |
+---------------+--------------------------------------+
| created_at    | 2026-03-09T16:18:16Z                 |
| error         |                                      |
| instance_uuid | 5a124ea0-36a0-49b8-9bd0-e937d958ca8f |
| result        | data: null                           |
|               | err_truncated: false                 |
|               | exitcode: 0                          |
|               | out_truncated: false                 |
|               | pid: 3216                            |
| status        | SUCCESS                              |
| type          | exec                                 |
| updated_at    | 2026-03-09T16:18:17Z                 |
| uuid          | bc57dbec-38cd-43b8-94f4-0e247c3bbaa9 |
+---------------+--------------------------------------+

The status field indicates whether the guest agent successfully executed the request. The exitcode field reflects the return code of the process inside the guest OS:

• A value of 0 indicates successful execution.
• Non-zero values indicate an error condition defined by the executed program.

To write data to a file inside the guest OS

Use the following command:

vinfra service compute server command file-write <server> <vm-file> [-f <file> | -d <data>]

<server>

VM ID or name

<vm-file>

Path to a file inside the VM guest OS

-f <file>, --file <file>

Path to a local file to read from

-d <data>, --data <data>

Literal string data

If neither --file nor --data is specified, data is read from stdin.

Example 1. To write data from a local file local.txt to C:\file.txt inside the virtual machine vm1, run:

# vinfra service compute server command file-write vm1 C:\file.txt --file ./local.txt

Example 2. To write from literal data to C:\file.txt inside the virtual machine vm1, run:

# vinfra service compute server command file-write vm1 C:\file.txt --data "Hello world"

It is strongly recommended to verify the command status after file upload using the vinfra service compute server command show command. Even if the upload completes without error, verify the final command status to ensure that all data was successfully written inside the guest OS.

To read data from a file inside the guest OS

Use the following command:

vinfra service compute server command file-read <server> <vm-file> [-o <file>]

<server>

VM ID or name

<vm-file>

Path to a file inside the VM guest OS

-o <file>, --output <file>

Write output to a file instead of stdout

For example, to read data from a file C:\file.txt inside the virtual machine vm1 and save the output to a local file test.txt, run:

# vinfra service compute server command file-read vm1 C:\file.txt -o test.txt

If the operation is interrupted, verify the command status using the vinfra service compute server command show command.