The helper's hand-written Info.plist declared its extension point the way
an App Store upload was rejected for in Apple forums thread 803896 (ITMS-90349,
invalid EXExtensionPointIdentifier); Apple's fix was the documented helper
extension setup, which binds in code and lets Xcode generate the Info.plist
instead. Build settings in the binding are expanded, so UTM and UTM SE
still bind to their own host with any bundle prefix.
Assisted-by: Claude:claude-opus-5-5
visionOS installs extensions only for Apple's extension points, so an app
carrying the helper for our own qemu-helper extension point fails to install.
Build and embed the helper only for iOS and report it unsupported on
visionOS, which hides the qemu-img features as on iOS before 26.
Assisted-by: Claude:claude-opus-5-5
LLVM 15 finds libncurses in the iOS SDK and enables terminfo, which pulls
setupterm/tigetnum/set_curterm/del_curterm into dxmt-native. App Store
review rejects these as non-public API (ITMS-90338).
Assisted-by: Claude:claude-opus-5-5
The iOS-SE scheme has run with Address Sanitizer since the schemes were
first committed to set the architecture override, which was incidental.
An ExtensionKit extension linked with the sanitizer does not start on a
device, so every qemu-img operation of UTM SE failed when run from
Xcode. Turn it off, add the schemes Xcode created for the helper targets
so both can be built and debugged on their own, and take the Metal API
validation setting Xcode 27 writes into the macOS scheme.
Assisted-by: Claude:claude-fable-5-1
QEMU tools cannot run in the app process on iOS: a process may load QEMU
only once and qemu-img calls exit(). So disk snapshots of a stopped VM,
reclaiming space, compression, resizing and conversion on import were
macOS-only.
iOS 26 brings ExtensionKit, so qemu-img now runs in an ExtensionKit
extension (iOSHelper, and iOSHelper-SE for UTM SE since an extension's
bundle identifier must be prefixed by its host's). The helper speaks the
same QEMUHelperProtocol as the macOS XPC helper but loads the tool into
its own process, one tool per process. UTMProcess accepts an injected
connection so the remote path is shared with macOS, including file
access through bookmarks, whose implicit security scope grants the
resolving process access. UTMHelperProcess launches the helper and,
because the system hands a process that is still exiting to a launch
that comes too soon, tears it down with a handshake on the interruption
callback and runs helpers one at a time.
UTMQemuImage now reads the tool's output until it ends instead of
racing the exit message, resumes its continuations off the XPC reply
queue (a call made from that queue blocks in NSXPC), and stops the
process explicitly since the connection's exported object kept it from
ever being deallocated on macOS. The last stderr line becomes the error
text when the tool gives none.
Assisted-by: Claude:claude-fable-5-1
The Mesa host build now installs a build machine copy of the KosmicKrisp
driver into host/lib. It has the same architecture in every sysroot, so
lipo refuses to combine it.
Assisted-by: Claude:claude-opus-5-5
The other Vulkan driver values are integers, and the raw value is
read back as one, so the string entry was inconsistent with its
siblings.
Assisted-by: Claude:claude-fable-5-1
The new Mesa revision builds KosmicKrisp with the precompiled shader
compiler, and the driver now needs macOS 26 (and the aligned iOS,
tvOS, and visionOS 26 releases) at runtime. Bump the availability
gates on the settings picker and the VM start check to match.
Assisted-by: Claude:claude-fable-5-1
Cutting a release meant hand-assembling notes that the app parses for
"What's New", and Release.md no longer matched the template in use. The
skill drafts the notes from the commits and PRs since the last release
(carrying the series forward on revisions), waits for approval, then
bumps Build.xcconfig, tags, and creates the release and its Releases
discussion. Release.md now holds the current template and footer and
documents which platform prefixes the in-app parser accepts.
Assisted-by: Claude:claude-opus-5-5
On macOS 26 and later, the borderless button menu style draws the
Devices "New…" entry as a compact pull-down: smaller text, an untinted
icon, a chevron, and a text column that does not line up with the other
sidebar rows. Only the button menu style combined with the plain button
style renders the label like the neighbouring rows, so use that on
macOS 26 and keep the existing style on older releases and on iOS.
Assisted-by: Claude:claude-fable-5-1
The macOS notes box was a TextEditor with a hand-drawn half-point
border, which did not match the bezel of the name field above it and
had no focus ring. A TextField with a vertical axis has the right look
but submits on Return instead of inserting a newline, and a drawn
overlay cannot follow the bezel style of each macOS release.
Wrap an NSTextField configured for wrapping instead, so AppKit draws
the same bezel, highlight and focus ring as the name field on every
supported macOS version. Return is routed through the field editor
to insert a newline, the field grows with its contents from a 200pt
minimum, and the page's disableAutocorrection setting is applied to
the field editor as the TextEditor did. iOS keeps the TextEditor.
Assisted-by: Claude:claude-fable-5-1
The QEMU settings page listed UTM's generated arguments next to the
editable custom ones in a single list, which made users think the
generated arguments could be changed and invited pasting options found
online that do not apply to UTM's build of QEMU.
Move custom arguments to their own page, edited through a popover on
macOS and a pushed page on iOS like port forwarding, instead of inline
text fields that needed SwiftUI workarounds. On macOS the page is hidden
behind a checkbox on the QEMU page that is only on while the settings
sheet is open unless the VM already has custom arguments; a short
disclaimer sits under the checkbox and under the iOS row. The complete
command line is shown as read-only selectable text, so the export
command feature is removed.
Assisted-by: Claude:claude-fable-5-1
Since the input and output streams were merged into a single
virtio-sound device, playing audio in the guest also opens the host
microphone, which switches Bluetooth headphones into headset mode.
Replace the "Enable Sound" toggle with a choice of input only, output
only, or both so users can avoid opening the microphone.
The existing "Audio" key keeps meaning output and a new "AudioInput"
key is added. When "AudioInput" is missing it defaults to "Audio", so
existing configs keep both streams and new configs still load on older
versions of UTM.
Resolves#7875
Assisted-by: Claude:claude-opus-5-5
Gives agents a repeatable way to exercise a change in the real app before
/utm-review: build UTM and dependencies, repackage a single dependency
with scripts/fixup.sh, create and delete a throwaway test VM by scripting,
find logs, debug, and test headless GUI and the iOS simulator.
Assisted-by: Claude:claude-opus-5-5
Repackaging one dependency after a change previously meant re-running the
whole build_dependencies.sh. Move the framework fixup into scripts/fixup.sh
so it can be run on its own, and have build_dependencies.sh call it.
Standalone use needed two fixes: re-running no longer nests symlinks
inside an existing Versions/Current (ln -h) and updates Info.plist keys
instead of skipping them, and imports are also matched by file name so
a sysroot built elsewhere (e.g. a CI artifact) is rewritten correctly.
Output for a full build is unchanged.
Assisted-by: Claude:claude-opus-5-5
Keystrokes typed into a QEMU VM's built-in terminal never reached the
guest. SPICE sends port writes by reference after CSPort returns, and
since the CocoaSpice update in cebbab9d drains an autorelease pool on
every SPICE loop iteration, the bytes were freed before they were sent.
Pull in the CocoaSpice fix that keeps the data alive until the write
completes.
Fixes#7814
Assisted-by: Claude:claude-opus-5-5
SwiftTerm 2 no longer exposes the underlying Terminal from TerminalView, so
move the terminal views to the copied view APIs: terminalDimensions,
resize(cols:rows:), setCursorStyle, softReset and resetToInitialState. The
view's resize also soft resets the terminal now, so only call it when the
saved size differs, otherwise every resume would reset the guest's modes.
Track SwiftTerm from the osy/SwiftTerm fork's fix/visionos-build branch
for now: upstream main reads UIWindow.screen, which does not exist on
visionOS, and the fork reads the display scale from the trait collection
instead so the visionOS build works again.
SwiftTerm now ships a build tool plugin, which needs two changes to
build_utm.sh for CI. Xcode refuses to run a package plugin the machine has
not trusted, so pass -skipPackagePluginValidation. And -sdk also applies
to host tools, so the plugin's generator was built for the target platform
instead of the Mac and the build could not find it; pick the platform
with a generic destination and the architectures with ARCHS instead.
Also match the SDK name macosx when picking the default macOS scheme.
Take advantage of what the update brings:
- Render with Metal on macOS and iOS, falling back to Core Graphics if the
GPU pipeline cannot be created. visionOS stays on Core Graphics because
SwiftTerm's Metal path draws at the wrong scale there.
- Release the renderer with updateUiClosed() when the terminal window
closes or the iOS view is dismantled, as SwiftTerm now requires.
- Feed guest output straight from the serial port thread; feed() is
thread-safe now, so the hop to the main queue is no longer needed.
- Add the standard Edit > Find menu on macOS, which the terminal's new
find bar is driven from.
- Open only http(s) links from the terminal. SwiftTerm now also turns host
file paths printed by the guest into links, and its default handler on
macOS opens any URL or existing host path, so clicking one could launch
a host app. On iOS, let the bell use SwiftTerm's default haptic instead
of an empty override.
Assisted-by: Claude:claude-opus-5
Assisted-by: Claude:claude-opus-5-5
A VM's window is kept after it stops and run(vm:) reuses it as is. The Edit
button closes it before opening the settings, but AppleScript's update
configuration did not. If the displays were removed that way, the next start
got the old display window, which looks up the now missing display 0 and
crashes with an index out of range.
Close the window before updating the configuration, like the Edit button does,
so the next start creates the right kind of window.
Resolves#7882
Assisted-by: Claude:claude-opus-5-5
The snapshot commands could only name a snapshot and could not say anything
about it. A script could not tell when a snapshot was taken, how much it
holds, whether restoring it resumes the guest or starts it up, or whether
its data has gone missing, and there was no way to rename one or to throw
away a suspended state, both of which the window offers.
Make a snapshot an object instead. A virtual machine now has snapshots as
elements, each carrying those details, so a script can pick one out and
read it:
tell application "UTM"
set vm to virtual machine named "Debian"
set candidates to (snapshots of vm whose includes running state)
restore (item 1 of candidates)
end tell
Renaming is setting the name, and the commands that act on a snapshot take
the snapshot itself. Creating one returns it. Two more commands cover what
the window can do and scripting could not: scanning the images for
snapshots made by other tools, and discarding a saved state so the guest
starts up instead of resuming.
This replaces the snapshot commands of the 5.0.5 beta, which addressed a
snapshot by name through its virtual machine, so scripts and utmctl calls
written against them have to be updated.
Snapshots are addressed by name, so names are now kept apart the way
virtual machine names are, by appending a number.
Deleting a snapshot is its own command rather than the standard delete,
which coerces a specifier for anything inside a virtual machine into the
virtual machine itself; deleting that would throw away far more than was
asked for. The delete command refuses such a specifier for the same reason.
UTMScripting.swift is regenerated from the sdef; only the hunks that
changed are taken.
Assisted-by: Claude:claude-opus-5
The tab was built against a list that only held its entries in memory. Read
them from the VM instead, and send every action to UTMSnapshotService.
Which actions a snapshot offers now follows what the backend can do in the
state the VM is in, so a snapshot that cannot be restored right now says so
by being unavailable rather than by failing afterwards.
qemu-img is only part of the macOS app, so a VM whose snapshots cannot be
managed at all shows the details on their own as before.
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5
Apple virtualization reported snapshots as unsupported. It has no notion of
them, but the pieces are there: the disks can be layered and the saved
state and firmware storage are ordinary files.
Add a backend that freezes a layer per drive and keeps copies of the saved
state, the EFI variables and the macOS auxiliary storage beside them. The
layers under a disk that is attached cannot be changed, so a running VM may
only delete; everything else waits until it stops.
A layer sits beside the image it belongs to and is named after it, and the saved
state and firmware of a snapshot are copies named the same way. A bundle only
keeps the files its configuration names, so saving the configuration would take
all of them with it. Work out what the snapshots still need instead — the layer
being written to, the layers of the snapshots in the bundle, and whatever lies
underneath those — and keep exactly that, so anything left over is still cleaned
up. When that cannot be worked out, because the manifest or a layer cannot be
read, everything named after the file is kept instead.
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5
Snapshots were read straight out of the QEMU images by the scripting
commands, which only worked while the VM was off and knew nothing beyond
the tags in the image.
Put a backend behind the operations instead. Which one is chosen depends on
whether the VM is running, and each says what it can do in that state:
- A running VM goes through the QEMU monitor, which saves and loads the
whole machine along with the disks.
- A VM that is off goes through qemu-img, which can only save and revert
disk contents. Nothing may touch the images while QEMU has them open, so
a snapshot of disks alone is left alone until the VM stops.
Either way a snapshot spans every writable image, the UEFI variable store
included, because QEMU refuses to load one that any of them is missing. A
snapshot that some of them lack, such as one taken before a drive was added,
is kept but cannot be restored, which is not the same as its state being
gone: reverting only some of the drives would leave them at different points
in time. Reclaiming space rebuilds an image without its snapshots, so it is
refused while there are any.
UTMSnapshotService sits above the backend and keeps the manifest and the
stored state consistent: it marks entries whose state has disappeared when
an operation fails, and the first time a VM is opened it adopts whatever
snapshots are already in the images so that snapshots taken by other tools
are not lost. Both wait until the VM is stopped, because a running QEMU
lists the snapshots of every drive together, removable ones included.
Suspending is folded into the same mechanism. A VM now suspends to a
snapshot of its own rather than always the same name, so a suspended state
can be kept as a snapshot without copying it, and restoring a snapshot
makes the VM resume from it. The state is deleted once nothing refers to
it, where it used to be left behind in the image. One that cannot be deleted
right away stays listed in the manifest and is tried again the next time.
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5
A snapshot has a title, a date, a size, a screenshot and the snapshot it
was based on. None of that fits in the image formats the backends use, so
keep it in a new `snapshots.plist` in the VM bundle where each entry links
to the state in the backend by identifier.
The file also remembers which snapshot the current state came from and
which state the VM resumes from while it is suspended, along with the
states that are no longer needed but could not be deleted yet.
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5
DiskImageKit can put a copy-on-write layer on an image and remembers what
each layer sits on. Use that to freeze the contents of a drive: the layer
holding what the guest has written so far is closed off under the name of a
snapshot and a fresh one is opened above it for further writes.
Layers are kept beside the image as `<image>.<name>.asif`. A layer whose
snapshot is deleted cannot be merged away while other layers are stacked on
it, so it is only marked as unlinked and is swept once nothing needs it.
Attachments are built through the same path so that a drive with layers is
opened as the whole stack, and a disposable run adds its throwaway layer on
top of it.
A stack is only ever opened whole. When one of its layers cannot be read the
drive is not attached at all: opening the rest without it would hide what it
holds, and falling back to the bare image would write underneath every layer
stacked on it. For the same reason a layer to write to is always put in place
before the one it replaces goes, and the image under a stack cannot be resized.
Nor can a drive with layers be attached read only, which a stack cannot be, or
before macOS 27, which cannot read the layers: the image alone is the drive as
it was before the first snapshot. Removable media never has layers.
Assisted-by: Claude:claude-fable-5-1
Assisted-by: Claude:claude-opus-5
Wrap `qemu-img snapshot` so the internal snapshots of an image can be
listed, created, applied and deleted while QEMU is not running.
Assisted-by: Claude:claude-fable-5-1
Snapshots could only be managed through scripting. Split the details view
into tabs (a tab view on macOS and a segmented control elsewhere, following
the HIG) and add a Snapshots tab next to the existing details.
The tab lists the current state followed by every snapshot, newest first,
along a timeline. A snapshot never changes unless it is overwritten, and
restoring one replaces the current state with a copy, so the actions say as
much: the current state can be saved as a new snapshot or overwrite the one
it is based on, and a snapshot can be restored or deleted. Anything that
loses data asks first.
A snapshot is based on whatever the current state was based on when it was
created. One that follows what it is based on is joined to it so a lineage
without branches reads as a single line. A base that is elsewhere in the
list is named by a link instead, which keeps branches of any depth from
widening the list. The lineage of the focused row is highlighted and only
that row shows its actions. Rows choose their layout from the measured
width because a regular size class can still be narrow next to the sidebar.
The operations only modify an in-memory list for now and no snapshots are
read from the VM yet.
Whether a snapshot holds the running machine decides whether restoring it
resumes the guest or starts it up, so the mark on the timeline is filled for one
that does and hollow for one that holds only the disks.
Assisted-by: Claude:claude-fable-5-1
qemu-img reports most failures, such as an image that cannot be opened, by
returning from main rather than by exiting. The launcher dropped that value
and always exited with 0, so on macOS a conversion, resize or snapshot
operation that failed looked like it had succeeded. Snapshots of a VM that
is off depend on those errors to know that a state was not deleted or
reverted.
Assisted-by: Claude:claude-opus-5
osy