vagrant_utm 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e9244b20397925333750f59097f53ae24d91d577a2b576bb9708575900e6322
-  data.tar.gz: 661fdde402f8e5524c615ca564f2e2996ba802faae4e9def172c3cc40ad4b675
+  metadata.gz: ec09354bc45c159ba048b7965ffd6802e865a3f60e99e74d2bdd5f9bb5bf3166
+  data.tar.gz: 001d7226ab9fdd498d8340b0a095eaebe1774424418095f0a73fbb42e04fc1c9
 SHA512:
-  metadata.gz: 443831d9674fa2256109ecae5d40bbd6e25034e6226287188238e2659d7b8e9ba6628b5bf26bbfed4e16e06000724b8008f39c099c5a4b018aaba2715fd00728
-  data.tar.gz: 21a86fd8e831745d6cac5b48d3b7d582e033be905afc1de4b1206984d8a9a9c6e8020ecd428c6a2dda11628d0ac4880ed44b6821ad144ac7321eebfb42343bc9
+  metadata.gz: d83c1d82fdcb5dc2983edd7b16c4a72b76b934a7b66bb379b80e46e85a70a6ad0b2e1720c56f1311f3cc42f465034d08acf66c78f8a6ddac15c155ab0b001236
+  data.tar.gz: 5247adf195d74c9992cb03451baa55f5ac5c7c5d4bc8a58f2e651b73f044bcf806fe7a8ed66a43119e549bf2c8df754e7c137f75119394c31155626e5c7662e7

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-14
+
+### Added
+- Use UTM 5.0.6's native snapshot API through `utmctl` for supported QEMU
+  and Apple Virtualization VMs (Apple snapshots require macOS 27).
+- Support UTM 5.0.4+ VLAN guest and DHCP network properties through
+  `network_interface` and `update_network_interface`.
+
+### Changed
+- Let UTM handle snapshot creation, listing, restoration, and deletion across
+  supported VM states.
+- Stop a running VM before restoring a snapshot to avoid UTM's live restore RPC
+  timeout, then restart it unless Vagrant's `--no-start` option is given.
+
+### Removed
+- Remove the `qemu-img` snapshot workaround. Snapshots now require UTM 5.0.6 or
+  newer; keep an older plugin release if you need snapshots on older UTM.
+
 ## [0.1.6] - 2026-08-14
 
 ### Added
@@ -94,4 +112,4 @@ IMPORTANT: This version of the plugin only works with UTM version 4.5.1 and abov
 ## [0.0.1] (Pilot release) - 2024-08-08 
 
 * Initial release with all basic vagrant commands
-* Uses UTM file in zip format from a url as VM box to import
+* Uses UTM file in zip format from a url as VM box to import

data/README.md

@@ -27,7 +27,7 @@ vagrant up
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, follow the [release steps](notes/README.md#to-release). The tag-triggered GitHub Actions workflow builds and publishes the gem.
 
 ### Vagrant
 

data/docs/commands.md

@@ -9,7 +9,7 @@ nav_order: 2
 
 This page lists all the supported Vagrant commands which depend on the  UTM provider. Eg. `up`, `suspend`, `resume`, `halt`.
 
-Adds note to the command which are have some limitations. Eg. `snapshot`.
+Adds notes to commands which have provider-specific behavior. Eg. `snapshot`.
 
 The Vagrant commands that do not depend on provider are not listed and will continue to work. Eg. `global-status`
 
@@ -84,13 +84,23 @@ This resumes a Vagrant managed machine that was previously suspended, perhaps wi
 
 **Command: `vagrant snapshot`**
 
-{: .warning }
-Snapshot feature is not available in UTM. 
-The plugin just provides experimental feature using qemu-img 
+`utmctl snapshot`
 
-Vagrant UTM provider supports offline snapshots using 
-qemu-img. Hence only VM with single qcow2 file is supported.
+With UTM 5.0.6 or newer, the provider uses UTM's native named snapshots.
+UTM supports QEMU snapshots on macOS. Apple Virtualization snapshots require
+macOS 27. A snapshot of a running QEMU VM includes its running state; a
+snapshot of a stopped VM saves its disks. UTM handles saving, listing, and
+deleting snapshots through its native API.
 
+`vagrant snapshot restore` stops a running VM before restoring its snapshot.
+Vagrant starts the restored VM afterward unless `--no-start` is given. UTM may
+resume saved RAM state when the restored VM next starts. The provider does not call
+`utmctl discard-state` during a restore, because that would discard the saved
+running state.
+
+Older UTM releases do not expose the 5.0.6 snapshot API. This plugin no longer uses
+`qemu-img` as a fallback. If you need snapshots on UTM older than 5.0.6,
+keep the previous plugin version that paired with that UTM release.
 
 
 ## **SSH**

data/docs/configuration.md

@@ -27,6 +27,35 @@ config.vm.provider "utm" do |u|
 end
 ```
 
+## Shared network VLAN / DHCP (UTM 5.0.4+)
+
+UTM 5.0.4 exposed AppleScript properties for the shared/host network VLAN subnet and DHCP pool ([utmapp/UTM#7710](https://github.com/utmapp/UTM/pull/7710)), so you no longer need to set them manually in the UTM UI ([utmapp/UTM#3294](https://github.com/utmapp/UTM/issues/3294)).
+
+Index `0` is typically the first (Shared Network) adapter used by Vagrant boxes:
+
+```ruby
+config.vm.provider "utm" do |u|
+  u.network_interface 0,
+    vlan_guest_address: "192.168.222.0/24",
+    vlan_dhcp_start_address: "192.168.222.2",
+    vlan_dhcp_end_address: "192.168.222.254",
+    isolate_from_host: false
+end
+```
+
+Optional keys: `vlan_guest_address`, `vlan_guest_address_ipv6`, `vlan_dhcp_start_address`, `vlan_dhcp_end_address`, `isolate_from_host`.
+
+You can also call the driver directly when the machine already exists:
+
+```ruby
+machine.provider.driver.update_network_interface(
+  0,
+  vlan_guest_address: "192.168.222.0/24",
+  vlan_dhcp_start_address: "192.168.222.2",
+  vlan_dhcp_end_address: "192.168.222.254"
+)
+```
+
 ## Other customization
 
 ```ruby

data/docs/internals/actions.md

@@ -7,15 +7,16 @@ nav_order: 1
 
 The Table below maps the vagrant commands to the corresponding UTM commands that are executed.
 
-| Vagrant               | utmctl / AppleScript |
-| ---                   | ------------------ | 
-| `vagrant up`          | `utmctl start` | 
-| `vagrant halt`        | `utmctl stop` |
-| `vagrant suspend`     | `utmctl suspend` | 
-| `vagrant resume`      | `utmctl start` | 
-| `vagrant reload`      |  update configuration of vm with config |
-| `vagrant destroy`     | `utmctl delete` | 
-| `vagrant status`      | `utmctl status` | 
-| `vagrant disposable`  | `utmctl start --disposable` | 
-| `vagrant snapshot`    | `qemu-img snapshot`         |
-| `vagrant ip-address`  | `utmctl ip-address`         |
+| Vagrant | utmctl / AppleScript |
+| --- | --- |
+| `vagrant up` | `utmctl start` |
+| `vagrant halt` | `utmctl stop` |
+| `vagrant suspend` | `utmctl suspend` |
+| `vagrant resume` | `utmctl start` |
+| `vagrant reload` | update configuration of vm with config |
+| `vagrant destroy` | `utmctl delete` |
+| `vagrant status` | `utmctl status` |
+| `vagrant disposable` | `utmctl start --disposable` |
+| `vagrant snapshot` | `utmctl snapshot` |
+| `vagrant ip-address` | `utmctl ip-address` |
+| Provider `network_interface` (UTM 5.0.4+) | AppleScript network VLAN/DHCP properties |

data/docs/internals/utm_api.md

@@ -23,8 +23,8 @@ So we rely on Apple Scripting Bridge scripts which can be executed using `osascr
 When it comes to writing the OSA scripts, our first choice is applescript language due to its simplicity and support.
 But, if we need to exchange complex data like json from UTM to plugin we use Javascript (Note: Some APIs are difficult to get it working in JS, hence our first choice is applescript).
 
-**3. Shell command** : 
-All interactions with UTM should be possible with `utmctl` or `osascript`. But, due to the unavailablity of certain commands or features, we work around the issue by using direct shell command.  
-For Example:
+**3. Shell command** :
+All interactions with UTM should be possible with `utmctl` or `osascript`.
+Direct shell commands are reserved for capabilities that UTM does not expose.
 
-* Snapshot `qemu-img snapshot ...`
+Snapshots use UTM's native `utmctl snapshot` commands.

data/docs/known_issues.md

@@ -19,6 +19,5 @@ Draw back -  UTM does not expose export API. (UTM already has 'Share')~~
 
 4. Hide: Any plugin action will bring up the main UTM window. However, a properly built UTM box with no display will run headless.
 
-5. vagrant snapshot: Even though UTM does not have snapshot feature, this plugin has a experimental support for offline VM snapshots using qemu-img. 
-The VM must be stopped, for any snapshot commands to work.
-The snapshot only works for **single** qcow2 based VM images
+5. `vagrant snapshot` requires UTM 5.0.6 or newer (native `utmctl snapshot`).
+   There is no `qemu-img` fallback in this plugin version.

data/lib/vagrant_utm/action/customize.rb

@@ -13,7 +13,7 @@ module VagrantPlugins
           @event = event
         end
 
-        def call(env) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+        def call(env)
           customizations = []
           env[:machine].provider_config.customizations.each do |event, command|
             customizations << command if event == @event
@@ -24,26 +24,35 @@ module VagrantPlugins
 
             # Execute each customization command.
             customizations.each do |command|
-              processed_command = command.collect do |arg|
-                arg = env[:machine].id if arg == :id
-                arg.to_s
-              end
-
-              begin
-                env[:machine].provider.driver.execute_osa_script(
-                  processed_command
-                )
-              rescue VagrantPlugins::Utm::Errors::CommandError => e
-                raise Vagrant::Errors::VMCustomizationFailed, {
-                  command: command,
-                  error: e.inspect
-                }
-              end
+              execute_customization(env, command)
             end
           end
 
           @app.call(env)
         end
+
+        private
+
+        def execute_customization(env, command)
+          if command.first == :network_interface
+            env[:machine].provider.driver.update_network_interface(command[1], command[2])
+          else
+            execute_osa_customization(env, command)
+          end
+        rescue VagrantPlugins::Utm::Errors::CommandError => e
+          raise Vagrant::Errors::VMCustomizationFailed, {
+            command: command,
+            error: e.inspect
+          }
+        end
+
+        def execute_osa_customization(env, command)
+          processed_command = command.map do |arg|
+            arg = env[:machine].id if arg == :id
+            arg.to_s
+          end
+          env[:machine].provider.driver.execute_osa_script(processed_command)
+        end
       end
     end
   end

data/lib/vagrant_utm/action.rb

@@ -14,7 +14,6 @@ module VagrantPlugins
       autoload :CheckAccessible, action_root.join("check_accessible")
       autoload :CheckCreated, action_root.join("check_created")
       autoload :CheckGuestAdditions, action_root.join("check_guest_additions")
-      autoload :CheckQemuImg, action_root.join("check_qemu_img")
       autoload :CheckRunning, action_root.join("check_running")
       autoload :CheckUtm, action_root.join("check_utm")
       autoload :ClearForwardedPorts, action_root.join("clear_forwarded_ports")
@@ -266,17 +265,9 @@ module VagrantPlugins
       def self.action_snapshot_delete
         Vagrant::Action::Builder.new.tap do |b|
           b.use CheckUtm
-          b.use CheckQemuImg
           b.use Call, Created do |env, b2|
             if env[:result]
-              # qemu-img needs write-lock to file, so VM should be stopped
-              b2.use Call, IsStopped do |env2, b3|
-                if env2[:result]
-                  b3.use SnapshotDelete
-                else
-                  b3.use MessageNotStopped
-                end
-              end
+              b2.use SnapshotDelete
             else
               b2.use MessageNotCreated
             end
@@ -288,20 +279,19 @@ module VagrantPlugins
       def self.action_snapshot_restore # rubocop:disable Metrics/AbcSize
         Vagrant::Action::Builder.new.tap do |b|
           b.use CheckUtm
-          b.use CheckQemuImg
           b.use Call, Created do |env, b2|
             raise Vagrant::Errors::VMNotCreatedError unless env[:result]
 
             b2.use CheckAccessible
+            # Restoring a running QEMU VM can leave UTM waiting for its RPC.
+            # Stop it first, then let Vagrant honor --no-start below.
             b2.use EnvSet, force_halt: true
             b2.use action_halt
-            b2.use SnapshotRestore
-
-            b2.use Call, IsEnvSet, :snapshot_delete do |env2, b3|
-              b3.use action_snapshot_delete if env2[:result]
-            end
-
             b2.use Call, IsEnvSet, :snapshot_start do |env2, b3|
+              b3.use SnapshotRestore
+              b3.use Call, IsEnvSet, :snapshot_delete do |env3, b4|
+                b4.use action_snapshot_delete if env3[:result]
+              end
               b3.use action_start if env2[:result]
             end
           end
@@ -312,17 +302,9 @@ module VagrantPlugins
       def self.action_snapshot_save
         Vagrant::Action::Builder.new.tap do |b|
           b.use CheckUtm
-          b.use CheckQemuImg
           b.use Call, Created do |env, b2|
             if env[:result]
-              # qemu-img does offline snapshot, so VM should be stopped
-              b2.use Call, IsStopped do |env2, b3|
-                if env2[:result]
-                  b3.use SnapshotSave
-                else
-                  b3.use MessageNotStopped
-                end
-              end
+              b2.use SnapshotSave
             else
               b2.use MessageNotCreated
             end

data/lib/vagrant_utm/cap.rb

@@ -27,13 +27,7 @@ module VagrantPlugins
       def self.snapshot_list(machine)
         return [] if machine.id.nil?
 
-        begin
-          machine.provider.driver.list_snapshots(machine.id)
-        rescue VagrantPlugins::Utm::Errors::CommandError => e
-          raise Errors::SnapShotCommandFailed, {
-            stderr: e.inspect
-          }
-        end
+        machine.provider.driver.list_snapshots(machine.id)
       end
     end
   end

data/lib/vagrant_utm/config.rb

@@ -7,6 +7,13 @@ module VagrantPlugins
   module Utm
     # This is the configuration class for the UTM provider.
     class Config < Vagrant.plugin("2", :config)
+      NETWORK_OPTION_FLAGS = {
+        vlan_guest_address: "--vlan-guest-address",
+        vlan_guest_address_ipv6: "--vlan-guest-address-ipv6",
+        vlan_dhcp_start_address: "--vlan-dhcp-start-address",
+        vlan_dhcp_end_address: "--vlan-dhcp-end-address"
+      }.freeze
+
       # If true, will check if guest additions are installed and up to
       # date. By default, this is true.
       #
@@ -123,6 +130,33 @@ module VagrantPlugins
         customize("pre-boot", ["customize_vm.applescript", :id, "--directory-share-mode", mode_code])
       end
 
+      # Configure VLAN / DHCP settings on a UTM network interface.
+      #
+      # Maps to the AppleScript network properties added in UTM 5.0.4
+      # (utmapp/UTM#7710). These apply to shared/host network modes and let
+      # you pin the guest subnet / DHCP pool without editing the UTM UI
+      # (see utmapp/UTM#3294).
+      #
+      # @param index [Integer] network interface index (0 = first adapter)
+      # @param options [Hash]
+      # @option options [String] :vlan_guest_address IPv4 subnet CIDR (e.g. "192.168.222.0/24")
+      # @option options [String] :vlan_guest_address_ipv6 IPv6 prefix (e.g. "fec0::/64")
+      # @option options [String] :vlan_dhcp_start_address first DHCP pool address
+      # @option options [String] :vlan_dhcp_end_address last DHCP pool address
+      # @option options [Boolean] :isolate_from_host isolate guest from host
+      # @return [void]
+      def network_interface(index, **options)
+        if network_option_arguments(options).empty?
+          raise Vagrant::Errors::ConfigInvalid,
+                errors: "network_interface requires at least one of: " \
+                        "vlan_guest_address, vlan_guest_address_ipv6, " \
+                        "vlan_dhcp_start_address, vlan_dhcp_end_address, " \
+                        "isolate_from_host"
+        end
+
+        customize("pre-boot", [:network_interface, index, options])
+      end
+
       # This is the hook that is called to finalize the object before it
       # is put into use.
       def finalize!
@@ -161,6 +195,26 @@ module VagrantPlugins
       def to_s
         "UTM"
       end
+
+      private
+
+      def network_option_arguments(options)
+        NETWORK_OPTION_FLAGS.flat_map do |key, flag|
+          option_argument(flag, options[key])
+        end + isolate_from_host_argument(options[:isolate_from_host])
+      end
+
+      def option_argument(flag, value)
+        return [] if value.nil? || value.to_s.empty?
+
+        [flag, value.to_s]
+      end
+
+      def isolate_from_host_argument(value)
+        return [] if value.nil?
+
+        ["--isolate-from-host", value ? "true" : "false"]
+      end
     end
   end
 end

data/lib/vagrant_utm/driver/base.rb

@@ -39,6 +39,26 @@ module VagrantPlugins
         # @return [Boolean]
         def check_qemu_guest_agent; end
 
+        # Create a named full-VM snapshot.
+        def create_snapshot(_machine_id, _snapshot_name)
+          snapshot_unsupported!
+        end
+
+        # Delete a named full-VM snapshot.
+        def delete_snapshot(_machine_id, _snapshot_name)
+          snapshot_unsupported!
+        end
+
+        # List named full-VM snapshots.
+        def list_snapshots(_machine_id)
+          snapshot_unsupported!
+        end
+
+        # Restore a named full-VM snapshot.
+        def restore_snapshot(_machine_id, _snapshot_name)
+          snapshot_unsupported!
+        end
+
         # Forwards a set of ports for a VM.
         #
         # This will not affect any previously set forwarded ports,
@@ -103,6 +123,14 @@ module VagrantPlugins
         # @return [Hash]
         def read_network_interfaces; end
 
+        # Update VLAN / DHCP settings on a network interface (UTM 5.0.4+).
+        #
+        # @param [Integer] index Network interface index
+        # @param [Hash] options VLAN / DHCP options
+        def update_network_interface(_index, _options = {})
+          raise Errors::UtmInvalidVersion, supported_versions: "5.0.4+"
+        end
+
         # Sets the MAC address of the first network adapter.
         #
         # @param [String] mac MAC address without any spaces/hyphens.
@@ -333,6 +361,11 @@ module VagrantPlugins
 
         private
 
+        def snapshot_unsupported!
+          raise Errors::UtmInvalidVersion,
+                supported_versions: "5.0.6+ (required for snapshots)"
+        end
+
         # List of LANG values to attempt to use
         LANG_VARIATIONS = %w[C.UTF-8 C.utf8 en_US.UTF-8 en_US.utf8 C POSIX].map(&:freeze).freeze
 

data/lib/vagrant_utm/driver/meta.rb

@@ -121,6 +121,7 @@ module VagrantPlugins
                        :start,
                        :start_disposable,
                        :suspend,
+                       :update_network_interface,
                        :vm_exists?
 
         protected

data/lib/vagrant_utm/driver/version_4_5.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "log4r"
-require "etc"
-require "vagrant/util/platform"
 
 require File.expand_path("base", __dir__)
 
@@ -38,50 +36,11 @@ module VagrantPlugins
           output.include?("root")
         end
 
-        def create_snapshot(machine_id, snapshot_name)
-          list_result = list
-          machine_name = list_result.find(uuid: machine_id).name
-          machine_file = get_vm_file(machine_name)
-          execute_shell("qemu-img", "snapshot", "-c", snapshot_name, machine_file)
-        end
-
-        def delete_snapshot(machine_id, snapshot_name)
-          list_result = list
-          machine_name = list_result.find(uuid: machine_id).name
-          machine_file = get_vm_file(machine_name)
-          execute_shell("qemu-img", "snapshot", "-d", snapshot_name, machine_file)
-        end
-
         def export(_path)
           @logger.info("This version of UTM does not support exporting VMs
             Please upgrade to the latest version of UTM or UTM 'Share' feature in UI to export the virtual machine")
         end
 
-        def list_snapshots(machine_id) # rubocop:disable Metrics/AbcSize
-          list_result = list
-          machine_name = list_result.find(uuid: machine_id).name
-          machine_file = get_vm_file(machine_name)
-          output = execute_shell("qemu-img", "snapshot", "-l", machine_file)
-
-          return [] if output.nil? || output.strip.empty?
-
-          @logger.debug("list_snapshots_here: #{output}")
-
-          result = []
-          output.split("\n").map do |line|
-            result << ::Regexp.last_match(1).to_s if line =~ /^\d+\s+(\w+)/
-          end
-
-          result.sort
-        end
-
-        def restore_snapshot(machine_id, snapshot_name)
-          list_result = list
-          machine_name = list_result.find(uuid: machine_id).name
-          machine_file = get_vm_file(machine_name)
-          execute_shell("qemu-img", "snapshot", "-a", snapshot_name, machine_file)
-        end
-
         def forward_ports(ports) # rubocop:disable Metrics/CyclomaticComplexity
           args = []
           ports.each do |options|
@@ -112,31 +71,6 @@ module VagrantPlugins
           execute_osa_script(command) unless args.empty?
         end
 
-        def get_vm_file(vm_name)
-          # Get the current username
-          username = ENV["USER"] || Etc.getlogin
-
-          data_path = "/Users/#{username}/Library/Containers/com.utmapp.UTM/Data/Documents/#{vm_name}.utm/Data"
-          # Define the regex for UUID pattern
-          pattern = /^\b[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}\b.qcow2$/
-
-          # List the files in the directory and filter by regex
-          matching_files = Dir.entries(data_path).select do |file|
-            file.match?(pattern)
-          end
-
-          if matching_files.length == 1
-            # If there is exactly one matching file, return full path to file
-            "#{data_path}/#{matching_files[0]}"
-          elsif matching_files.length > 1
-            # If there are multiple matching files, raise an error
-            raise Errors::SnapShotMultipleVMFiles, directory: data_path, files: matching_files
-          else
-            # If there are no matching files, raise an error
-            raise Errors::SnapShotVMFileNotFound, directory: data_path
-          end
-        end
-
         # Check if the VM with the given UUID  exists.
         def vm_exists?(uuid)
           list_result = list

data/lib/vagrant_utm/driver/version_5_0.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require File.expand_path("version_4_7", __dir__)
 
 module VagrantPlugins
@@ -7,11 +9,108 @@ module VagrantPlugins
     module Driver
       # Driver for UTM 5.0.x
       class Version_5_0 < Version_4_7 # rubocop:disable Naming/ClassAndModuleCamelCase
+        # UTM AppleScript VLAN network properties land in 5.0.4
+        # (utmapp/UTM#7710).
+        VLAN_NETWORK_MIN_VERSION = "5.0.4"
+        NETWORK_OPTION_FLAGS = {
+          vlan_guest_address: "--vlan-guest-address",
+          vlan_guest_address_ipv6: "--vlan-guest-address-ipv6",
+          vlan_dhcp_start_address: "--vlan-dhcp-start-address",
+          vlan_dhcp_end_address: "--vlan-dhcp-end-address"
+        }.freeze
+        SNAPSHOT_MIN_VERSION = "5.0.6"
+
         def initialize(uuid)
           super
 
           @logger = Log4r::Logger.new("vagrant::provider::utm::version_5_0")
         end
+
+        # Update VLAN / DHCP settings on a network interface.
+        #
+        # These properties apply to shared/host network modes and map to the
+        # AppleScript fields added in utmapp/UTM#7710 (UTM 5.0.4+).
+        #
+        # @param [Integer] index Network interface index (0-based)
+        # @param [Hash] options
+        # @option options [String] :vlan_guest_address IPv4 subnet CIDR
+        # @option options [String] :vlan_guest_address_ipv6 IPv6 prefix
+        # @option options [String] :vlan_dhcp_start_address DHCP pool start
+        # @option options [String] :vlan_dhcp_end_address DHCP pool end
+        # @option options [Boolean] :isolate_from_host Isolate guest from host
+        def update_network_interface(index, options = {})
+          require_vlan_network_support!(__method__)
+
+          args = ["--index", index.to_s] + network_option_arguments(options)
+
+          if args.length == 2
+            raise ArgumentError,
+                  "update_network_interface requires at least one network option"
+          end
+
+          command = ["update_network_interface.applescript", @uuid] + args
+          execute_osa_script(command)
+        end
+
+        def create_snapshot(machine_id, snapshot_name)
+          require_snapshot_support!
+          execute("snapshot", "create", machine_id, "--name", snapshot_name)
+        end
+
+        def delete_snapshot(machine_id, snapshot_name)
+          require_snapshot_support!
+          execute("snapshot", "delete", machine_id, "--snapshot", snapshot_name)
+        end
+
+        def list_snapshots(machine_id)
+          require_snapshot_support!
+          output = execute("snapshot", "list", machine_id, "--json")
+          JSON.parse(output).map { |snapshot| snapshot.fetch("name") }
+        end
+
+        def restore_snapshot(machine_id, snapshot_name)
+          require_snapshot_support!
+          execute("snapshot", "restore", machine_id, "--snapshot", snapshot_name)
+        end
+
+        private
+
+        def network_option_arguments(options)
+          NETWORK_OPTION_FLAGS.flat_map do |key, flag|
+            option_argument(flag, options[key])
+          end + isolate_from_host_argument(options[:isolate_from_host])
+        end
+
+        def option_argument(flag, value)
+          return [] if value.nil? || value.to_s.empty?
+
+          [flag, value.to_s]
+        end
+
+        def isolate_from_host_argument(value)
+          return [] if value.nil?
+
+          ["--isolate-from-host", value ? "true" : "false"]
+        end
+
+        def require_vlan_network_support!(method_name)
+          version = read_utm_version
+          return if Gem::Version.new(version) >= Gem::Version.new(VLAN_NETWORK_MIN_VERSION)
+
+          raise Errors::UtmInvalidVersion,
+                supported_versions: "#{VLAN_NETWORK_MIN_VERSION}+ " \
+                                    "(required for #{method_name})"
+        end
+
+        def require_snapshot_support!
+          return if Gem::Version.new(read_utm_version) >= Gem::Version.new(SNAPSHOT_MIN_VERSION)
+
+          snapshot_unsupported!
+        end
+
+        def read_utm_version
+          @read_utm_version ||= execute("version").strip
+        end
       end
     end
   end

data/lib/vagrant_utm/errors.rb

@@ -52,26 +52,6 @@ module VagrantPlugins
       class ForwardedPortInvalidProtocol < UtmError
         error_key(:forwarded_port_invalid_protocol)
       end
-
-      # This error is raised if the qemu-img is not detected.
-      class QemuImgRequired < UtmError
-        error_key(:qemu_img_required)
-      end
-
-      # This error is raised if the snapshot command failed.
-      class SnapShotCommandFailed < UtmError
-        error_key(:snapshot_command_failed)
-      end
-
-      # This error is raised if multiple VM files are found during snapshot.
-      class SnapShotMultipleVMFiles < UtmError
-        error_key(:snapshot_multiple_vm_files)
-      end
-
-      # This error is raised if the VM is not found.
-      class SnapShotVMFileNotFound < UtmError
-        error_key(:snapshot_vm_file_not_found)
-      end
     end
   end
 end

data/lib/vagrant_utm/scripts/update_network_interface.applescript

@@ -0,0 +1,86 @@
+---
+-- update_network_interface.applescript
+-- Update VLAN / DHCP settings on a UTM network interface (UTM 5.0.4+).
+--
+-- Usage:
+--   osascript update_network_interface.applescript <VM_UUID> --index <N> [options]
+--
+-- Options (all optional; omitted values are left unchanged):
+--   --vlan-guest-address <CIDR>          e.g. 192.168.222.0/24
+--   --vlan-guest-address-ipv6 <prefix>   e.g. fec0::/64
+--   --vlan-dhcp-start-address <IPv4>
+--   --vlan-dhcp-end-address <IPv4>
+--   --isolate-from-host <true|false>
+--
+-- These properties apply to shared/host network modes (see UTM #7710 / #3294).
+
+on run argv
+  set vmID to item 1 of argv
+  set nicIndex to missing value
+  set vlanGuestAddress to missing value
+  set vlanGuestAddressIpv6 to missing value
+  set vlanDhcpStartAddress to missing value
+  set vlanDhcpEndAddress to missing value
+  set isolateFromHost to missing value
+
+  repeat with i from 2 to (count of argv)
+    set currentArg to item i of argv
+    if currentArg is "--index" then
+      set nicIndex to item (i + 1) of argv as integer
+    else if currentArg is "--vlan-guest-address" then
+      set vlanGuestAddress to item (i + 1) of argv
+    else if currentArg is "--vlan-guest-address-ipv6" then
+      set vlanGuestAddressIpv6 to item (i + 1) of argv
+    else if currentArg is "--vlan-dhcp-start-address" then
+      set vlanDhcpStartAddress to item (i + 1) of argv
+    else if currentArg is "--vlan-dhcp-end-address" then
+      set vlanDhcpEndAddress to item (i + 1) of argv
+    else if currentArg is "--isolate-from-host" then
+      set isolateArg to item (i + 1) of argv
+      if isolateArg is "true" or isolateArg is "yes" or isolateArg is "1" then
+        set isolateFromHost to true
+      else
+        set isolateFromHost to false
+      end if
+    end if
+  end repeat
+
+  if nicIndex is missing value then
+    error "Missing required --index <nicIndex>"
+  end if
+
+  tell application "UTM"
+    set vm to virtual machine id vmID
+    set config to configuration of vm
+    set networkInterfaces to network interfaces of config
+    set updated to false
+
+    repeat with anInterface in networkInterfaces
+      if nicIndex is index of anInterface then
+        if vlanGuestAddress is not missing value then
+          set vlan guest address of anInterface to vlanGuestAddress
+        end if
+        if vlanGuestAddressIpv6 is not missing value then
+          set vlan guest address ipv6 of anInterface to vlanGuestAddressIpv6
+        end if
+        if vlanDhcpStartAddress is not missing value then
+          set vlan dhcp start address of anInterface to vlanDhcpStartAddress
+        end if
+        if vlanDhcpEndAddress is not missing value then
+          set vlan dhcp end address of anInterface to vlanDhcpEndAddress
+        end if
+        if isolateFromHost is not missing value then
+          set isolate from host of anInterface to isolateFromHost
+        end if
+        set updated to true
+      end if
+    end repeat
+
+    if updated is false then
+      error "Network interface index " & nicIndex & " not found"
+    end if
+
+    -- VM must be stopped
+    update configuration of vm with config
+  end tell
+end run

data/lib/vagrant_utm/version.rb

@@ -4,6 +4,6 @@ module VagrantPlugins
   # Top level module for the Utm provider plugin.
   module Utm
     # Current version of the Utm provider plugin.
-    VERSION = "0.1.6"
+    VERSION = "0.2.0"
   end
 end

data/locales/en.yml

@@ -32,27 +32,6 @@ en:
         The virtual machine is not running.
       macos_required: |-
         MacOS is required to run this provider
-      qemu_img_required: |-
-        qemu-img is required to use snapshot feature.
-        You can install qemu-img using `brew install qemu`.
-      snapshot_command_failed: |-
-        There was an error while executing `qemu-img`, a CLI used by vagrant-utm
-        for managing UTM snapshots. qemu-img only supports offline operations, so
-        the VM must be stopped before any snapshot operation.
-        The error is shown below.
-
-        Error: %{stderr} 
-      snapshot_multiple_vm_files: |-
-        Multiple VM files detected. vagrant-utm which uses qemu-img does not support 
-        snapshot feature when multiple VM files are present.
-
-        Directory checked: %{directory}
-        Files found: %{files}
-      snapshot_vm_file_not_found: |-
-        VM file not detected. vagrant-utm checks for single qcow2 file named in 
-        UUID format in VM's data directory.
-
-        Directory checked: %{directory}
       utm_import_failed: |-
         UTM virtual machine import failed.
       utmctl_error: |-

data/notes/README.md

@@ -16,20 +16,34 @@ cd docs
 bundle exec jekyll serve
 ```
 
-To release 
+To release
 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`
-GitHub action upon tag push with "v*" will publish gem to GHR and rubygems
+Publishing is done by GitHub Actions. Pushing a tag matching "v*" triggers `.github/workflows/gem.yml`,
+which builds the gem once and then publishes it to GitHub Packages and rubygems.org, and creates the
+GitHub release with the `.gem` attached.
 
-1. Update 
-  CHANGELOG.md
+So locally we only bump the version and push the tag.
+
+1. Update
+  CHANGELOG.md (move the `[Unreleased]` entries under a new `[x.y.z] - YYYY-MM-DD` heading)
   version number in `version.rb`
-  version number Gemlock file
-2. Commit 
-3. Run `bundle exec rake release` (Commit and tags are pushed)
-4. Cancel push to rubygems.org 
+  version number in `Gemfile.lock` (the `vagrant_utm (x.y.z)` line under `PATH`)
+2. Commit
+3. Run `bundle exec rake release:guard_clean release:source_control_push`
+   (checks the tree is clean, creates the annotated tag, pushes the commit and the tag)
+4. Watch the run: `gh run watch $(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')`
+
+Do not run plain `bundle exec rake release`. It appends `release:rubygem_push`, which publishes the gem
+from your machine and duplicates what GHA already does — the old workaround was to cancel that push by
+hand, which is a race you can lose. Running the two subtasks above is the same flow without the race.
+
+After the run, confirm the gem actually shipped what you expect:
 
-GHA will publish gems to GHR and rubygems
+```bash
+gem unpack vagrant_utm-x.y.z.gem
+# every shipped applescript should be ASCII; non-ASCII bytes broke 0.1.5 (see #50)
+file vagrant_utm-x.y.z/lib/vagrant_utm/scripts/*.applescript
+```
 
 
 To update specific gems in the project
@@ -48,3 +62,15 @@ Unable to resolve dependency: user requested 'vagrant_utm (= 0.1.1)'
 
 Due to mismatch versions between global installed version and plugin version in the development setup, since they are same name.
 Fix: Uninstall the global version, while using different version of development setup
+
+If `bundle install` fails building grpc
+
+```
+third_party/zlib/zutil.h:147: #define fdopen(fd,mode) NULL
+_stdio.h:320: error: expected identifier or '('
+```
+
+grpc 1.56.2 (pulled in by the pinned vagrant 2.4.1) vendors a zlib that defines `fdopen` to `NULL` on
+macOS, which newer Xcode clang rejects. CI is unaffected because Linux uses a precompiled grpc, so the
+test suite still runs there. Until the vagrant pin moves, `rake` also works without `bundle exec`, which
+is enough to run the release subtasks above.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vagrant_utm
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Naveenraj M
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies: []
 description: Vagrant UTM provider that allows you to manage UTM virtual machines.
 email:
@@ -57,7 +57,6 @@ files:
 - lib/vagrant_utm/action/check_accessible.rb
 - lib/vagrant_utm/action/check_created.rb
 - lib/vagrant_utm/action/check_guest_additions.rb
-- lib/vagrant_utm/action/check_qemu_img.rb
 - lib/vagrant_utm/action/check_running.rb
 - lib/vagrant_utm/action/check_utm.rb
 - lib/vagrant_utm/action/clear_forwarded_ports.rb
@@ -126,6 +125,7 @@ files:
 - lib/vagrant_utm/scripts/read_shared_folders_args.js
 - lib/vagrant_utm/scripts/remove_qemu_additional_args.applescript
 - lib/vagrant_utm/scripts/set_mac_address.applescript
+- lib/vagrant_utm/scripts/update_network_interface.applescript
 - lib/vagrant_utm/synced_folder.rb
 - lib/vagrant_utm/util/compile_forwarded_ports.rb
 - lib/vagrant_utm/util/unix_mount_helpers.rb

data/lib/vagrant_utm/action/check_qemu_img.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module VagrantPlugins
-  module Utm
-    module Action
-      # This action checks if qemu-img is installed.
-      class CheckQemuImg
-        def initialize(app, _env)
-          @app = app
-        end
-
-        def call(env)
-          qemu_img_present = Vagrant::Util::Which.which("qemu-img")
-          raise Errors::QemuImgRequired unless qemu_img_present
-
-          @app.call(env)
-        end
-      end
-    end
-  end
-end