Nearly headless VMs Using utmctl

I’ve been using UTM since I switched to Apple silicon macs, but I recently discovered it’s cli tool, utmctl. It’s completely changed how I mange UTM and VMs on my macs.

How to install

utmctl is included when you install UTM (via the AppStore or package download available on their website). Once installed, you should have the utmctl command in a terminal:

iryan@venusaur ~ $ utmctl
OVERVIEW: CLI tool for controlling UTM virtual machines.

USAGE: utmctl <subcommand>

OPTIONS:
  -h, --help              Show help information.

SUBCOMMANDS:
  list                    Enumerate all registered virtual machines.
  status                  Query the status of a virtual machine.
  start                   Start a virtual machine or resume a suspended virtual machine.
  suspend                 Suspend running a virtual machine to memory.
  stop                    Shuts down a running virtual machine.
  attach                  Redirect the serial input/output to this terminal.
  file                    Guest agent file operations.
  exec                    Execute an application on the guest.
  ip-address              List all IP addresses associated with network interfaces on the guest.
  clone                   Clone an existing virtual machine.

  See 'utmctl help <subcommand>' for detailed help.

Commands

The utmctl options are all rather straightforward. I most often use the commands utmctl list, utmctl start VMNAME, and utmctl ip-address VMNAME. However, some of the other options, such as exec and attach, look interesting.

A quick example - Running (nearly) ‘headless’ VMs

The main improvement that utmctl has provided me is the ability to run my VMs “headless” (mostly), which I am accustomed to doing on Linux. To do this:

• Install and configure a VM in UTM, and ensure that ssh is enabled so it will automatically start on boot. Also, verify that you can properly ssh into the VM.

# Enable ssh to start. Likely this command on most linux systems:
sudo systemctl enable sshd

• Remove the virtual display in the VM’s settings. This will prevent the VM window from opening while it is running, as there is no GUI for the VM to run.

• Use utmctl to list or check the status of the VM(s).

ryan@venusaur ~ $ utmctl list
UUID                                 Status   Name
D77A861B-61DD-483A-BA09-D647C77EB77A stopped  nixos
EADB0899-8B20-48B9-BD23-B179E3C258B3 stopped  fedora

-- or --

ryan@venusaur ~ $ utmctl status fedora
stopped

• Use utmctl to start the VM:

ryan@venusaur ~ $ utmctl start fedora

ryan@venusaur ~ $ utmctl status fedora
started

• Use utmctl to get the ip address from the running VM (it might take a minute until the VM is fully started to work):

ryan@venusaur ~ $ utmctl ip-address fedora
192.168.64.33
fda6:d2b:ac2e:c75a:f87:fc14:d8fc:ef8d
fe80::6b82:d89b:3f27:9c3d

• ssh into the VM using the ip-address:

ryan@venusaur ~ $ ssh ryan@192.168.64.33
Last login: Fri Jul 28 05:43:17 2023
[ryan@fedora ~]$ # I'm in the VM!

• Although I usually shutdown the VM from inside it (which is recommended), you can alternatively shut it down using utmctl:

ryan@venusaur ~ $ utmctl status fedora
started
ryan@venusaur ~ $ utmctl stop fedora
ryan@venusaur ~ $ utmctl status fedora
stopped

After moving the display device, running these steps may still leave the UTM application open in the Dock, but the VM window should not pop up. It’s why I consider this to be a “mostly headless” process.

Conclusion

I love a simple but useful cli tool, and utmctl has been just that. I am glad that the team added it, and that it continues to get updates. For me, it immensely improves my experience using UTM. In fact, while writing this post I finally went and bought the App Store version of UTM to help support the developers. If you also love UTM, I encourage you to do the same.