The URL scheme utm is associated with the UTM app. To launch or bring to foreground UTM, open the URL utm:// (for example Safari, Shortcuts “Open URL” action, Automator).
Supported Commands
Commands marked ⚠️ can result in data loss or corruption in the guest VM, as the VM is shut down improperly.
| Command | Parameter(s) | Result | Example |
|---|---|---|---|
start | name of the VM | The VM with the provided name is started, if it’s not already started. | utm://start?name=Ubuntu%2020.04 |
stop | name of the VM | The VM with the provided name is stopped immediately. ⚠️ | utm://stop?name=Ubuntu%2020.04 |
restart | name of the VM | The VM with the provided name is stopped immediately, then started again. ⚠️ | utm://restart?name=Ubuntu%2020.04 |
pause | name of the VM | The VM with the provided name is paused. (not supported for all VMs) | utm://pause?name=Ubuntu%2020.04 |
resume | name of the VM | The VM with the provided name is resumed (un-paused). | utm://resume?name=Ubuntu%2020.04 |
sendText | name of the VM and text to be typed in the VM | The VM with the provided name receives the supplied text as keyboard input. | utm://sendText?name=Ubuntu%2020.04&text=abcdef (types “abcdef” in the VM) |
click | name of the VM, x and y position to click, optional: mouse button to click (left/middle/right, default left) | The VM with the provided name receives a mouse click down and up event at the specified pixel location. | utm://click?name=Ubuntu%2020.04&x=10&y=125&button=right (right clicks at (10/125) in the VM) |
downloadVM | url to the VM, must be ZIP file of a .utm package (URL must contain .zip). | Downloads the ZIP file (progress shown in UTM with cancel button), then extracts and imports the contained .utm file. | utm://downloadVM?url=https%3A%2F%2Fchrisp.cafe%2FUTM%2FXP.zip (downloads a VM template for Windows XP) |
Note on the sendText action: you can send ASCII Control Codes to the VM, here are some common ones:
- Esc is
%1b - Delete (backspace) is
%08 - Tab is
%09 - Enter is
%0D
URL Parameter Encoding
The parameters like name, text, and url need to be URL encoded so they are received correctly. For example, if the VM “Ubuntu 20.04” should be addressed, the name parameter is “Ubuntu%2020.04”. If you’re using Shortcuts “Open URL” action, this is done automatically. Otherwise you can use apps like Boop or websites like DuckDuckGo or Dan’s Tools URL Encode Decode to perform the encoding.
UTM Automation using Shortcuts (macOS 12 Monterey and iOS)
- URL action with the parameter utm://start?name=Ubuntu 20.04
- Open URLs action
Start a VM automatically when you log in (macOS 12 Monterey)
First, create a Shortcut to launch the VM as shown above. Then, select the shortcut in the list and choose File → Add to Dock.
The Shortcut will appear in your Dock. Hold down the ⌘ (cmd) key while clicking on the icon in the Dock to reveal the Shortcut file in Finder. A Finder window will open in the folder ~/Applications/. Add the Shortcut file to your Login Items (System Preferences → Users and Groups → Login Items):
To stop the VM from starting at login, open the Login Items page again, select the Shortcut in the list, and press the minus button (-).
UTM for Mac Automation using Automator (macOS 11 Big Sur)
Here is an example Workflow created in Automator:
- Get Specified Text: utm://start?name=Ubuntu%2020.04
- Extract URLs from Text
- Display Webpages
Start a VM automatically when you log in (macOS 11 Big Sur)
To start a VM automatically when you log in to your Mac, create an Automator workflow like above to start the VM you want. Then add it to your Login Items (System Preferences → Users and Groups → Login Items).
