August 2019

VBoxHeadless

VBoxHeadless 1
VBoxHeadless &product-name; remote desktop server &product-name;
`VBoxHeadless` --startvm= uuid vmname --vrde= on off config --vrdeproperty=prop-name=prop-value --settingspw=password --settingspwfile=password-file --start-paused --capture --width=width --height=height --bitrate=bit-rate --filename=filename

## Description

The `VBoxHeadless` command is an alternate front end that enables you to remotely manage virtual machines (VMs). The front end is a CLI rather than the VirtualBox Manager graphical user interface (GUI).

For information about using this command, see .

### Command Options

`--startvm=uuid | vmname`

  Specifies the Universally Unique Identifier (UUID) or name of the VM to start.

  Use the `VBoxManage list vms` command to obtain VM information.

  The short versions of this option is `-s`.

`--vrde=on | off | config`

  Specifies how to use the VRDP server. The default value is `config`. Valid values are as follows:

  - `on` enables the VRDP server.

        VBoxHeadless --startvm=vmname --vrde=on

  - `off` disables the VRDP server.

        VBoxHeadless --startvm=vmname --vrde=off

  - `config` enables the VRDP server depending on the VM configuration.

        VBoxHeadless --startvm=vmname --vrde=config

  The short version of this option is `-v`.

`--vrdeproperty=prop-name=[prop-value]`

  Specifies a value for one of the following properties:

  - The `TCP/Ports` property value is a comma-separated list of ports to which the VRDE server can bind. Use a hyphen (`-`) between two port numbers to specify a range of ports.

  - The `TCP/Address` property value is the interface IP address to which to bind the VRDE server.

`--settingspw=password`

  Specifies a settings password to access encrypted settings. If you do not specify the password on the command line, `VBoxHeadless` prompts you for the password.

  This design does not conform to Oracle's security guidelines. You should not be able to specify a password on the command line because the password can be seen in a process listing.
`--settingspwfile=password-file`

  Specifies the file that contains the settings password.

`--start-paused`

  Starts the specified VM in the paused state.

`--capture`

  Records the VM screen output to a file. In addition to this option, you must use the `--filename` option to specify the name of the file.

`--width=width`

  Specifies the frame width of the recording in pixels. This option is associated with the `--capture` option.

`--height=height`

  Specifies the frame height of the recording in pixels. This option is associated with the `--capture` option.

`--bitrate=bit-rate`

  Specifies the bit rate of the recording in kilobits per second. This option is associated with the `--capture` option.

`--filename=filename`

  Specifies the name of the file in which to store the recording. The codec used is based on the file extension that you choose. You must specify this option if you use the `--capture` option.

  Where can we get information about the file extensions that are supported?

## Examples

The following command starts the `ol7u4` VM:

    $ VBoxHeadless --startvm "ol7u4"

The following command starts the `ol7u6` VM in the Paused state.

    $ VBoxHeadless --startvm "ol7u6" --start-paused

The following command starts the `ol7u6` VM and records the session. The recording is saved to the `ol7u6-recording` WebM file.

    $ VBoxHeadless --startvm "ol7u6" --capture --filename ol7u6-recording.webm

## See Also

,