Udon is under active development. Documentation not final.
udonudon
Virtual machines

Virtual machines

Create Linux virtual machines from a template or your own installer image, publish their ports on the Mac, open their console from the dashboard, and keep them running across Udon restarts.

The Virtual machines page runs Linux guests on the Mac with Apple's Virtualization framework. Each VM is its own process started by the daemon, so a VM keeps running while Udon updates or restarts, and a crash in one VM never touches another. Guests get a private address the Mac can reach; ports you publish are forwarded from the Mac's own address, the way a container's ports are.

Today the page runs Linux guests only, and it needs a Mac with Apple silicon. macOS guests, snapshots and suspend to disk are on the way.

Create a VM

  1. Click + on the Machines tab.
  2. Pick what to install from. Debian 13 boots a ready-made cloud image and sets itself up from the first-user details you type, with no screen needed. Ubuntu Server 24.04 runs the installer, which you finish in the console window on the Mac. Custom image uses an ISO or raw disk image from the Images tab.
  3. If the template's image is not downloaded yet, click Download and wait for the progress bar to finish. Images live in a shared library, so a second VM from the same template needs no download.
  4. Set a name, the number of CPUs, memory and disk size, and where the disk goes: the Mac's own data folder, or another volume from the Store on list. Disks are sparse: a 32 GB disk takes only as much space as the guest writes.
  5. Add Published ports if a service in the guest should be reachable from your network: each row forwards a port on the Mac to a port in the guest. Host ports below 1024 are not offered.
  6. For a template that sets itself up, fill in First user: a username, and a password or an SSH public key, or both. Without either there is no way to sign in.
  7. Click Create. The VM appears in the list stopped; Start it from the row.

A VM with Start when Udon launches on starts after you sign in to the Mac.

Run it

The row shows the VM's state, CPU and memory use, its address once the guest has one, its published ports and how long it has run. Start and Stop sit on the row; the row's menu adds Force stop, Restart, Pause and Resume, Console, the console window, Edit and Remove. Stop asks the guest to shut down; Force stop pulls the plug.

Console opens the guest's serial console as a session on the Terminal page. Press Return once to get a login prompt; Debian's cloud image signs you in with the first user you set. The console shows the login prompt and what you type, not the kernel's boot messages.

Show window on this Mac opens the guest's screen in a window on the Mac itself, for installers and anything graphical. It is a window on that Mac's display, not a stream to the browser; close it any time without affecting the VM.

Viewers can look, changes need an operator, and creating, editing or removing a VM, the console and the window need an admin.

Edit, disks and removal

Open a VM to see its details, and Edit it from the row menu or the panel. The name, description, autostart switch and published ports change at any time. CPUs and memory change only while the VM is stopped.

The Disks tab adds a disk, grows one (never shrinks) and deletes any disk but the first, again only while the VM is stopped. Growing a disk makes the space available to the guest; extend the partition and file system inside the guest to use it. Eject detaches an installer image once the install is done.

Remove stops the VM and deletes its record. Tick Also delete its disks to free the space; otherwise the disk images stay in the VM's folder.

Images

The Images tab is the shared library of installer and disk images. Add downloads an image from an https address or copies a file that is already on the Mac. Templates download into the same library. An image that a VM still uses cannot be deleted; detach it first.

Ask AI

Answers from Udon's documentation.

Ask how to install Udon, run containers, or share folders.