Run and control VMs

Each running VM has its own process, so it keeps running when you close the MacVisor app or the VM's window.

Start and open

Start a VM from the library, the Virtual Machine menu, the menu bar item, or mvz start <vm>. It opens in its own window, or runs without one if it is set to headless.

Closing the window hides the VM by default. It keeps running and using memory. Change this per VM in VM Settings → General → When the Window Closes. Reopen a hidden VM from the library or with mvz open <vm>.

VM shortcuts use Control-Command so that ⌘S or ⌘P typed in a guest app never reach the VM menu. Capture Input sends system keys such as ⌘Tab to the guest. Click its toolbar button again to release.

In the main window, the Virtual Machine menu acts on the VM selected in the list, with the same kind of shortcuts. An item is greyed out when it doesn't apply to the VM's state.

The menu also has Take Snapshot… and Clone… for the selected VM. Move to Trash… and Erase and Install… are turned off for a VM protected from deletion.

Type Password and Type Clipboard

Type Password types the password of the account MacVisor made in the VM (macOS with automatic setup, Windows, Ubuntu Desktop, FreeBSD) into the VM's window as keystrokes. It works where pasting doesn't: the macOS login window and lock screen, the Windows sign-in screen and UAC prompts, the Ubuntu lock screen, and a FreeBSD VM's console. It's in the VM menu, on the toolbar (the key button), and on the VM's Overview while it runs.

• It types for the VM's keyboard layout (VM Settings > Keyboard & Pointer > Keyboard in the VM; see Keyboard & Pointer for the default). With U.S., a password with a character a U.S. keyboard can't type (such as é, ü, € or ß) is refused and nothing is typed. With Same as This Mac, it types with your Mac's current layout and refuses a character that layout can't type. Use Show Password instead, or change the setting.
• It never presses Return. Caps Lock must be off in the VM.

Type Clipboard (VM → Type Clipboard in the VM's window, ⌃⇧⌘V) types the text on your Mac's clipboard into the VM as keystrokes. Use it where clipboard sharing doesn't reach: an installer, a sign-in screen, a firmware or boot prompt, or a guest without guest tools. It works while the VM runs with its display shown and the clipboard holds text. The console has its own Edit → Paste.

• It types for Keyboard in the VM, as Type Password does. On U.S., it types what a U.S. keyboard types: letters without accents, digits, punctuation, spaces, tabs and line breaks. A macOS VM on Same as This Mac gets every character your Mac's layout types. A Windows, Linux or FreeBSD VM on Same as This Mac gets only what the Mac's layout and its PC version have on the same keys: everything a U.S. keyboard types from a U.S. or ABC layout, otherwise only letters and digits, spaces, tabs and line breaks. See Keyboard & Pointer.
• It checks the whole text first. If any character can't be typed, nothing is typed, and the alert names the first few. Clipboard sharing or a shared folder can carry the rest.
• Text with a line break, or of more than 1,000 characters, asks first, because each line is entered as it's typed, so a shell in the VM runs it as a command. Cancel is the default, so Return cancels. It types at most 20,000 characters at a time.
• It waits up to 2 seconds for you to let go of the shortcut's keys, and types nothing if they're still held.
• While it types, the window's subtitle counts the characters, and the item reads Stop Typing. Escape stops it too. Other keys you press in the window don't reach the VM until it's done.
• It stops when you switch to another window or app or to the console, or the VM pauses, suspends, takes a live snapshot or stops. The subtitle then says how far it got. No key is left held down in the VM.
• It's for the window only. AI agents can't use it, and their type_text tool types only the text an agent gives it.

Lifecycle actions

Stop reaches each guest differently. macOS and Windows guests are shut down by the MacVisor Agent, so apps get to save and no dialog appears. Before the agent connects, a macOS VM made with automatic setup is shut down over SSH. Linux guests get the virtual power button. If one hasn't started shutting down 15 seconds later and nothing in it took the button, the MacVisor Agent shuts it down, or a QEMU guest agent when MacVisor's agent can't be asked. Guests with neither get the button only. FreeBSD guests go through MacVisor's agent, a QEMU guest agent, SSH, then the power button, pressed again a minute later. See Shutting down.

A VM with a shutdown command, such as an appliance shut down over SSH, is shut down by that command instead, and MacVisor's own way follows if it fails. Power Off and Suspend never use it.

A paused VM is resumed first, so its guest can be asked. If a guest takes a while to shut down, MacVisor says what the guest reports is holding it up: for example unattended-upgrades installing updates on Ubuntu, a program holding a shutdown lock, a desktop asking on the guest's screen, or Windows waiting for an app with unsaved work or installing updates. The VM's window asks after 30 seconds, and a VM without a window gets a line in Tasks after a minute. A guest that is shutting down slowly, or whose desktop took the button, isn't asked again, and MacVisor never powers a guest off on its own, except in a restart you turned on for a health check or VM Watchdog: use Power Off only when you're sure nothing will be lost.

While a snapshot or suspend is being saved, only Power Off is available. It acts at once and abandons the save.

When a saved session won't restore

macOS only restores a saved session while you are logged in at the Mac with the screen unlocked. If it is locked, the VM waits. The Overview shows Waiting for the Mac to be unlocked, and the session stays intact.

If a restore fails for another reason, before the VM has run from the session, the Overview explains why and offers Try Again and Start from Disk…. Starting from disk discards the session but nothing on the disk.

Once the guest has begun running from a session, its disk has moved on, so the session can't be used again. If the restore fails after that point, or the VM's runner ends there, MacVisor discards the session and says so: start the VM from its disk. A VM set to start at login is started from its disk by itself, with a task saying its session couldn't be restored.

Saved memory, from a suspend or a live snapshot, only restores on the macOS release that saved it, and a MacVisor update can have the same effect. Shut VMs down, rather than suspending them, before you update macOS or MacVisor. See Updates. On macOS 27, VMs with disk caching set to Cached have sometimes failed to restore. See VM settings.

mvz show <vm>                        # explains why
mvz start <vm> --discard-state       # boot from disk instead

When you log out or restart the Mac

Choose what VMs do at logout, restart or shutdown in Settings → General → Logout and Shutdown. This also covers sudo shutdown -r now.

A longer wait holds up logging out or restarting the Mac. A VM that is busy starting, suspending or taking a snapshot gets up to a minute to finish first. sudo shutdown and launchctl reboot bypass the login window, so guests get 12 seconds in all. A Linux guest that ignores the power button is shut down by its agent within that time.

mvz service at-logout              # show the current choice
mvz service at-logout suspend      # or shutdown

Headless and autostart

mvz start <vm> --headless starts a VM without a window: mvz open <vm> shows one later. Headless in VM Settings → Display gives a VM no display at all, so it never has a window; reach it over SSH or mvz console. See VMs without a window. Start at Login has the background service start the VM at every login, with or without the app. To keep VMs running through unattended reboots, see Always-on host.

mvz start <vm> --headless
mvz wait <vm> --ssh             # until cloud-init is done and SSH answers
mvz ip <vm> --wait              # prints the IPv4 address; exits 5 after 10 minutes
mvz autostart <vm> on
mvz screenshot <vm> frame.jpg   # a preview; needs the window shown since the start, except Windows on Virtio-MVZ

mvz shell <vm> connects once SSH answers. It doesn't start a VM that isn't running: it says so and exits with status 6, unless you add --start, which starts it (or resumes it) first. If the agent never connects, wait --ssh returns three minutes after SSH first answers. See Waiting for a VM.

macOS guests get accelerated graphics. Linux guests use unaccelerated Virtio graphics. Resolution settings are in VM settings.

Serial console

Turn on Serial Console in VM Settings → Advanced, restart the VM, and run mvz console <vm>. Press Control-] to detach. It's on by default for Linux VMs and always on for FreeBSD VMs, off by default for macOS VMs, and not available for Windows VMs.

The VM's window shows the same console: Linux and FreeBSD VMs have a Display | Console switch in the toolbar, and any VM with a console has View → Show Console and Show Display (⌃⌘C). See Display and console for signing in at the console, mvz console --raw, and VMs without a window.