Introduce "tart exec" command as an alternative to SSH (#1074 )

* Introduce "tart exec" command as an alternative to SSH * Simplify control socket machinery by using NIO async/await primitives * No reason to print the "vm" object directly, just refer to it as "VM" * Log to Apple’s Unified Logging System
Fix unescaped commas in generated ArgumentParser completions (#1066 )
2026-10-01 19:51:10 +02:00 · 2025-05-22 17:28:14 +04:00 · 2025-05-06 14:24:43 +04:00 · 2025-05-04 20:49:23 -04:00 · 2025-04-29 21:15:03 +04:00 · 2025-04-29 18:10:14 +04:00
138 changed files with 5488 additions and 1233 deletions
@@ -7,6 +7,8 @@ export VERSION="${CIRRUS_TAG:-0}"
 mkdir -p .ci/pkg/
 cp .build/arm64-apple-macosx/release/tart .ci/pkg/tart
 cp Resources/embedded.provisionprofile .ci/pkg/embedded.provisionprofile
+cp Resources/AppIcon.png .ci/pkg/AppIcon.png
+cp Resources/Info.plist .ci/pkg/Info.plist
 pkgbuild --root .ci/pkg/ --identifier com.github.cirruslabs.tart --version $VERSION \
  --scripts .ci/pkg/scripts \
  --install-location "/Library/Application Support/Tart" \
@@ -3,9 +3,11 @@
 set -e

 # fix structure
-mkdir -p "$2/tart.app/Contents/MacOS"
+mkdir -p "$2/tart.app/Contents/MacOS" "$2/tart.app/Resources"
 mv "$2/tart" "$2/tart.app/Contents/MacOS/tart"
 mv "$2/embedded.provisionprofile" "$2/tart.app/Contents/embedded.provisionprofile"
+mv "$2/AppIcon.png" "$2/tart.app/Resources/AppIcon.png"
+mv "$2/Info.plist" "$2/tart.app/Contents/Info.plist"

 echo "#!/bin/sh" > /usr/local/bin/tart
 echo "exec '$2/tart.app/Contents/MacOS/tart' \"\$@\"" >> /usr/local/bin/tart
@@ -3,3 +3,5 @@
 TMPFILE=$(mktemp)
 envsubst < Sources/tart/CI/CI.swift > $TMPFILE
 mv $TMPFILE Sources/tart/CI/CI.swift
+
+/usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string ${CIRRUS_TAG}" Resources/Info.plist
@@ -1,27 +1,23 @@
 use_compute_credits: true

-env: 
-  XCODE_TAG: 15
-
 task:
-  name: Test on Sonoma
+  name: Test on Sequoia
  alias: test
  persistent_worker:
    labels:
      name: dev-mini
    resources:
      tart-vms: 1
+  build_script:
+    - swift build
  test_script:
    - swift test
  integration_test_script:
-    # Build Tart
-    - swift build
    - codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/debug/tart
    - export PATH=$(pwd)/.build/arm64-apple-macosx/debug:$PATH
    # Run integration tests
    - cd integration-tests
-    - HOMEBREW_NO_AUTO_UPDATE=1 brew install virtualenv
-    - virtualenv venv
+    - python3 -m venv --symlinks venv
    - source venv/bin/activate
    - pip install -r requirements.txt
    - pytest --verbose --junit-xml=pytest-junit.xml
@@ -41,7 +37,7 @@ task:
  name: Lint
  alias: lint
  macos_instance:
-    image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sequoia
  lint_script:
    - swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore --lint --report swiftformat.json .
  always:
@@ -51,14 +47,18 @@ task:

 task:
  only_if: $CIRRUS_TAG == ''
-  name: Build
+  env:
+    matrix:
+      BUILD_ARCH: arm64
+      BUILD_ARCH: x86_64
+  name: Build ($BUILD_ARCH)
  alias: build
  macos_instance:
-    image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG
-  build_script: swift build --product tart
-  sign_script: codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/debug/tart
+    image: ghcr.io/cirruslabs/macos-runner:sequoia
+  build_script: swift build --arch $BUILD_ARCH --product tart
+  sign_script: codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/$BUILD_ARCH-apple-macosx/debug/tart
  binary_artifacts:
-    path: .build/debug/tart
+    path: .build/$BUILD_ARCH-apple-macosx/debug/tart

 task:
  only_if: $CIRRUS_TAG == '' && ($CIRRUS_USER_PERMISSION == 'write' || $CIRRUS_USER_PERMISSION == 'admin')
@@ -67,7 +67,7 @@ task:
    - lint
    - build
  macos_instance:
-    image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sequoia
  env:
    MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
    AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
@@ -85,12 +85,11 @@ task:
  install_script:
    - brew install go goreleaser/tap/goreleaser-pro
    - brew install mitchellh/gon/gon
-    - curl -sL https://sentry.io/get-cli/ | sh
  info_script:
    - security find-identity -v
    - xcodebuild -version
    - swift -version
-  goreleaser_script: goreleaser release --skip-publish --snapshot --clean
+  goreleaser_script: goreleaser release --skip=publish --snapshot --clean
  always:
    dist_artifacts:
      path: "dist/*"
@@ -103,7 +102,7 @@ task:
    - test
    - build
  macos_instance:
-    image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sequoia
  env:
    MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
    AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
@@ -111,7 +110,7 @@ task:
    GORELEASER_KEY: ENCRYPTED[!9b80b6ef684ceaf40edd4c7af93014ee156c8aba7e6e5795f41c482729887b5c31f36b651491d790f1f668670888d9fd!]
    SENTRY_ORG: cirrus-labs
    SENTRY_PROJECT: persistent-workers
-    SENTRY_AUTH_TOKEN: ENCRYPTED[!c16a5cf7da5f856b4bc2f21fe8cb7aa2a6c981f851c094ed4d3025fd02ea59a58a86cee8b193a69a1fc20fa217e56ac3!]
+    SENTRY_AUTH_TOKEN: ENCRYPTED[!9eaf2875d51b113e2f68598441ff8e6b2e53242e48fcb93633bd75a373fbe2e7caa900d837cc92f0b142b65579731644!]
  setup_script:
    - cd $HOME
    - echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
@@ -121,7 +120,7 @@ task:
    - security import certificate.p12 -k build.keychain -P password101 -T /usr/bin/codesign -T /usr/bin/pkgbuild
    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
-  install_script: 
+  install_script:
    - brew install go goreleaser/tap/goreleaser-pro getsentry/tools/sentry-cli
    - brew install mitchellh/gon/gon
  info_script:
@@ -153,7 +152,7 @@ task:
    registry_config: ENCRYPTED[!cf1a0f25325aa75bad3ce6ebc890bc53eb0044c02efa70d8cefb83ba9766275a994b4831706c52630a0692b2fa9cfb9e!]
  env:
    DEPLOY_TOKEN: ENCRYPTED[!45ed45666558902ed1c2400add734ec063103bec31841847e8c8764802fca229bfa6d85c690e16ad159e047574b48793!]
-  deploy_script: 
+  deploy_script:
    - git config --global user.name "Cirrus CI"
    - git config --global user.name "hello@cirruslabs.org"
    - git remote set-url origin https://$DEPLOY_TOKEN@github.com/cirruslabs/tart/
@@ -16,3 +16,6 @@ dist/

 # mkdocs
 .cache
+
+# mkdocs-material
+site
@@ -1,22 +1,31 @@
+version: 2
+
 project_name: tart

 before:
  hooks:
    - .ci/set-version.sh
-    - swift build -c release --product tart
-    - gon gon.hcl
-    - mkdir -p tart.app/Contents/MacOS
-    - cp .build/arm64-apple-macosx/release/tart tart.app/Contents/MacOS/
+    - swift build --arch arm64 --configuration release --product tart
+    - swift build --arch x86_64 --configuration release --product tart

 builds:
-  - builder: prebuilt
+  - id: tart
+    builder: prebuilt
+    goamd64: [v1]
    goos:
      - darwin
    goarch:
      - arm64
+      - amd64
    binary: tart.app/Contents/MacOS/tart
    prebuilt:
-      path: tart.app/Contents/MacOS/tart
+      path: '.build/{{- if eq .Arch "arm64" }}arm64{{- else }}x86_64{{ end }}-apple-macosx/release/tart'
+
+universal_binaries:
+  - name_template: tart.app/Contents/MacOS/tart
+    replace: true
+    hooks:
+      post: gon gon.hcl

 archives:
  - name_template: "{{ .ProjectName }}"
@@ -24,6 +33,12 @@ archives:
      - src: Resources/embedded.provisionprofile
        dst: tart.app/Contents
        strip_parent: true
+      - src: Resources/Info.plist
+        dst: tart.app/Contents
+        strip_parent: true
+      - src: Resources/AppIcon.png
+        dst: tart.app/Contents/Resources
+        strip_parent: true
      - LICENSE

 release:
@@ -31,24 +46,25 @@ release:

 brews:
  - name: tart
-    tap:
+    repository:
      owner: cirruslabs
      name: homebrew-cli
-    caveats: See the GitHub repository for more information
+    caveats: |
+      Tart has been installed. You might want to reduce the default DHCP lease time
+      from 86,400 to 600 seconds to avoid DHCP shortage when running lots of VMs daily:
+
+        sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.InternetSharing.default.plist bootpd -dict DHCPLeaseTimeSecs -int 600
+
+      See https://tart.run/faq/#changing-the-default-dhcp-lease-time for more details.
    homepage: https://github.com/cirruslabs/tart
    license: "Fair Source"
-    description: Run macOS VMs on Apple Silicon
+    description: Run macOS and Linux VMs on Apple Hardware
    skip_upload: auto
    dependencies:
      - "cirruslabs/cli/softnet"
    install: |
      libexec.install Dir["*"]
      bin.write_exec_script "#{libexec}/tart.app/Contents/MacOS/tart"
+      generate_completions_from_executable(libexec/"tart.app/Contents/MacOS/tart", "--generate-completion-script")
    custom_block: |
      depends_on :macos => :ventura
-      
-      on_macos do
-        unless Hardware::CPU.arm?
-          odie "Tart only works on Apple Silicon!"
-        end
-      end
@@ -0,0 +1,64 @@
+# Profiling Tart
+
+## Using `time(1)`
+
+Perhaps, the easiest, but not the most comprehensive way to tell what's going on with Tart is to use the [`time(1)`](https://ss64.com/mac/time.html) command.
+
+In the example below, you will run `tart pull` via `time(1)` to gather generalized CPU, I/O and memory usage metrics:
+
+```shell
+/usr/bin/time -l tart pull ghcr.io/cirruslabs/macos-sequoia-base:latest
+```
+
+**Note:** you need to specify a full path to `time(1)` binary, otherwise the shell's built-in `time` command will be invoked, which doesn't have the `-l` command-line argument.
+
+**Note:** The `-l` command-line argument makes `time(1)` return much more useful information, for example, maximum memory usage.
+
+When running the command above, you'll see the `tart pull` output first as it pulls the image, and then the `time(1)` output, which will be printed once the Tart process finishes:
+
+```
+      172.17 real        10.29 user         8.36 sys
+           353796096  maximum resident set size
+                   0  average shared memory size
+                   0  average unshared data size
+                   0  average unshared stack size
+               23838  page reclaims
+                  35  page faults
+                   0  swaps
+                   0  block input operations
+                   0  block output operations
+                   8  messages sent
+                   8  messages received
+                   0  signals received
+                 146  voluntary context switches
+              222950  involuntary context switches
+         39683070975  instructions retired
+         27562035252  cycles elapsed
+           170920448  peak memory footprint
+```
+
+From the output above, you can tell that `tart pull` spent nearly 90% of time off-CPU (`real` > `user` + `sys`), which means that Tart was mostly waiting for the I/O (be it a network or disk), instead of decompressing disk layers or doing other useful computations.
+
+## Using `xctrace(1)`
+
+[`xctrace(1)`](https://keith.github.io/xcode-man-pages/xctrace.1.html) is a `.trace` format recorder for the [Instruments](https://en.wikipedia.org/wiki/Instruments_(software)) app, which yields much more powerful insights compared to `time(1)`. For example, it can tell which Tart functions spent the most time on the CPU, thus allowing the Tart developers to further optimize these functions.
+
+To use it, make sure that [Xcode](https://developer.apple.com/xcode/resources/) is installed. If you're installing Xcode for the first time on the machine, you'll need to launch it once and click the blue "Install" button. There's no need to choose any platforms except for the macOS.
+
+Once done, you can create a CPU profile of `tart pull`:
+
+```shell
+xctrace record --template "CPU Profiler" --target-stdout - --launch -- /opt/homebrew/bin/tart pull ghcr.io/cirruslabs/macos-sequoia-base:latest
+```
+
+Now that `xctrace(1)` is running, you'll see the `tart pull`-related output first, and once finished, the following line will appear:
+
+```
+Output file saved as: Launch_[...].trace
+```
+
+To view this trace in the Instruments app, simply find this directory in Finder and double-click it. Instruments app will appear:
+
+![](Resources/Instruments.png)
+
+To send this trace, right-click its directory in Finder and choose "Compress [...]". This will result in a similarly named file with a `.zip` at the end, which can now be conveniently sent via email or uploaded.
@@ -1,12 +1,31 @@
 {
+  "originHash" : "fe99b8634d39cad3971bde2180657a2bf711968e2e9cf5e3823bc51ea1530663",
  "pins" : [
    {
      "identity" : "antlr4",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/antlr/antlr4",
      "state" : {
-        "branch" : "dev",
-        "revision" : "2703a8516c0fb7fe92db6b9c40e0113f577646d2"
+        "revision" : "cc82115a4e7f53d71d9d905caa2c2dfa4da58899",
+        "version" : "4.13.2"
+      }
+    },
+    {
+      "identity" : "cirruslabs_tart-guest-agent_apple_swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://buf.build/gen/swift/git/1.28.2-00000000000000-dfeb75ad2b39.1/cirruslabs_tart-guest-agent_apple_swift.git",
+      "state" : {
+        "revision" : "3e13bec2dd36788e80a2e5a2022d44d4a1f373cf",
+        "version" : "1.28.2-00000000000000-dfeb75ad2b39.1"
+      }
+    },
+    {
+      "identity" : "cirruslabs_tart-guest-agent_grpc_swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://buf.build/gen/swift/git/1.24.2-00000000000000-dfeb75ad2b39.1/cirruslabs_tart-guest-agent_grpc_swift.git",
+      "state" : {
+        "branch" : "1.24.2-00000000000000-dfeb75ad2b39.1",
+        "revision" : "5b6ff43b580fe435f0a174e137e2b197759a7170"
      }
    },
    {
@@ -18,13 +37,31 @@
        "revision" : "772883073d044bc754d401cabb6574624eb3778f"
      }
    },
+    {
+      "identity" : "grpc-swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/grpc/grpc-swift.git",
+      "state" : {
+        "revision" : "8c5e99d0255c373e0330730d191a3423c57373fb",
+        "version" : "1.24.2"
+      }
+    },
+    {
+      "identity" : "semaphore",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/groue/Semaphore",
+      "state" : {
+        "revision" : "2543679282aa6f6c8ecf2138acd613ed20790bc2",
+        "version" : "0.1.0"
+      }
+    },
    {
      "identity" : "sentry-cocoa",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/getsentry/sentry-cocoa",
      "state" : {
-        "revision" : "d277532e1c8af813981ba01f591b15bbdd735615",
-        "version" : "8.8.0"
+        "revision" : "5575af93efb776414f243e93d6af9f6258dc539a",
+        "version" : "8.36.0"
      }
    },
    {
@@ -32,8 +69,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/apple/swift-algorithms",
      "state" : {
-        "revision" : "b14b7f4c528c942f121c8b860b9410b2bf57825e",
-        "version" : "1.0.0"
+        "revision" : "f6919dfc309e7f1b56224378b11e28bab5bccc42",
+        "version" : "1.2.0"
      }
    },
    {
@@ -41,17 +78,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/apple/swift-argument-parser",
      "state" : {
-        "revision" : "f3c9084a71ef4376f2fabbdf1d3d90a49f1fabdb",
-        "version" : "1.1.2"
-      }
-    },
-    {
-      "identity" : "swift-async-algorithms",
-      "kind" : "remoteSourceControl",
-      "location" : "https://github.com/apple/swift-async-algorithms",
-      "state" : {
-        "branch" : "main",
-        "revision" : "f05e450f0b909c0e80670a47516c4b9700b9e5da"
+        "revision" : "41982a3656a71c768319979febd796c6fd111d5c",
+        "version" : "1.5.0"
      }
    },
    {
@@ -59,8 +87,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/apple/swift-atomics.git",
      "state" : {
-        "revision" : "919eb1d83e02121cdb434c7bfc1f0c66ef17febe",
-        "version" : "1.0.2"
+        "revision" : "cd142fd2f64be2100422d658e7411e39489da985",
+        "version" : "1.2.0"
      }
    },
    {
@@ -68,8 +96,80 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/apple/swift-collections.git",
      "state" : {
-        "revision" : "f504716c27d2e5d4144fa4794b12129301d17729",
-        "version" : "1.0.3"
+        "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7",
+        "version" : "1.1.4"
+      }
+    },
+    {
+      "identity" : "swift-http-structured-headers",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-structured-headers.git",
+      "state" : {
+        "revision" : "db6eea3692638a65e2124990155cd220c2915903",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-http-types",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-types.git",
+      "state" : {
+        "revision" : "a0a57e949a8903563aba4615869310c0ebf14c03",
+        "version" : "1.4.0"
+      }
+    },
+    {
+      "identity" : "swift-log",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-log.git",
+      "state" : {
+        "revision" : "9cb486020ebf03bfa5b5df985387a14a98744537",
+        "version" : "1.6.1"
+      }
+    },
+    {
+      "identity" : "swift-nio",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio.git",
+      "state" : {
+        "revision" : "34d486b01cd891297ac615e40d5999536a1e138d",
+        "version" : "2.83.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-extras",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-extras.git",
+      "state" : {
+        "revision" : "f1f6f772198bee35d99dd145f1513d8581a54f2c",
+        "version" : "1.26.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-http2",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-http2.git",
+      "state" : {
+        "revision" : "4281466512f63d1bd530e33f4aa6993ee7864be0",
+        "version" : "1.36.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-ssl",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-ssl.git",
+      "state" : {
+        "revision" : "4b38f35946d00d8f6176fe58f96d83aba64b36c7",
+        "version" : "2.31.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-transport-services",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-transport-services.git",
+      "state" : {
+        "revision" : "cd1e89816d345d2523b11c55654570acd5cd4c56",
+        "version" : "1.24.0"
      }
    },
    {
@@ -81,13 +181,49 @@
        "version" : "1.0.2"
      }
    },
+    {
+      "identity" : "swift-protobuf",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-protobuf.git",
+      "state" : {
+        "revision" : "ebc7251dd5b37f627c93698e4374084d98409633",
+        "version" : "1.28.2"
+      }
+    },
+    {
+      "identity" : "swift-retry",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/fumoboy007/swift-retry",
+      "state" : {
+        "revision" : "df9d7b185d2e433147ec0083a73c257e665eea0d",
+        "version" : "0.2.4"
+      }
+    },
    {
      "identity" : "swift-sysctl",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/sersoft-gmbh/swift-sysctl.git",
      "state" : {
-        "revision" : "71fd64ee84819bb19fbecfb36d5a4503726b6fb7",
-        "version" : "1.6.0"
+        "revision" : "a91be36de6803ebe48f678699dfd0694c2200d2f",
+        "version" : "1.8.0"
+      }
+    },
+    {
+      "identity" : "swift-system",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-system.git",
+      "state" : {
+        "revision" : "a34201439c74b53f0fd71ef11741af7e7caf01e1",
+        "version" : "1.4.2"
+      }
+    },
+    {
+      "identity" : "swift-xattr",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/jozefizso/swift-xattr",
+      "state" : {
+        "revision" : "f8605af7b3290dbb235fb182ec6e9035d0c8c3ac",
+        "version" : "3.0.0"
      }
    },
    {
@@ -95,8 +231,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/malcommac/SwiftDate",
      "state" : {
-        "revision" : "6190d0cefff3013e77ed567e6b074f324e5c5bf5",
-        "version" : "6.3.1"
+        "revision" : "5d943224c3bb173e6ecf27295611615eba90c80e",
+        "version" : "7.0.0"
      }
    },
    {
@@ -104,8 +240,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/nicklockwood/SwiftFormat",
      "state" : {
-        "revision" : "da637c398c5d08896521b737f2868ddc2e7996ae",
-        "version" : "0.50.6"
+        "revision" : "ab6844edb79a7b88dc6320e6cee0a0db7674dac3",
+        "version" : "0.54.5"
      }
    },
    {
@@ -127,5 +263,5 @@
      }
    }
  ],
-  "version" : 2
+  "version" : 3
 }
@@ -1,4 +1,4 @@
-// swift-tools-version:5.7
+// swift-tools-version:5.10

 import PackageDescription
 let package = Package(
@@ -10,23 +10,26 @@ let package = Package(
    .executable(name: "tart", targets: ["tart"])
  ],
  dependencies: [
-    .package(url: "https://github.com/apple/swift-argument-parser", from: "1.1.2"),
+    .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.1"),
    .package(url: "https://github.com/mhdhejazi/Dynamic", branch: "master"),
-    .package(url: "https://github.com/apple/swift-algorithms", from: "1.0.0"),
-    .package(url: "https://github.com/apple/swift-async-algorithms", branch: "main"),
-    .package(url: "https://github.com/malcommac/SwiftDate", from: "6.3.1"),
-    .package(url: "https://github.com/antlr/antlr4", branch: "dev"),
-    .package(url: "https://github.com/apple/swift-atomics.git", .upToNextMajor(from: "1.0.0")),
-    .package(url: "https://github.com/nicklockwood/SwiftFormat", from: "0.50.6"),
-    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.8.0"),
+    .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
+    .package(url: "https://github.com/malcommac/SwiftDate", from: "7.0.0"),
+    .package(url: "https://github.com/antlr/antlr4", exact: "4.13.2"),
+    .package(url: "https://github.com/apple/swift-atomics.git", .upToNextMajor(from: "1.2.0")),
+    .package(url: "https://github.com/nicklockwood/SwiftFormat", from: "0.53.6"),
+    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.36.0"),
    .package(url: "https://github.com/cfilipov/TextTable", branch: "master"),
-    .package(url: "https://github.com/sersoft-gmbh/swift-sysctl.git", from: "1.0.0"),
-    .package(url: "https://github.com/orchetect/SwiftRadix", from: "1.3.0")
+    .package(url: "https://github.com/sersoft-gmbh/swift-sysctl.git", from: "1.8.0"),
+    .package(url: "https://github.com/orchetect/SwiftRadix", from: "1.3.1"),
+    .package(url: "https://github.com/groue/Semaphore", from: "0.0.8"),
+    .package(url: "https://github.com/fumoboy007/swift-retry", from: "0.2.3"),
+    .package(url: "https://github.com/jozefizso/swift-xattr", from: "3.0.0"),
+    .package(url: "https://github.com/grpc/grpc-swift.git", .upToNextMajor(from: "1.24.2")),
+    .package(url: "https://buf.build/gen/swift/git/1.24.2-00000000000000-dfeb75ad2b39.1/cirruslabs_tart-guest-agent_grpc_swift.git", revision: "1.24.2-00000000000000-dfeb75ad2b39.1"),
  ],
  targets: [
    .executableTarget(name: "tart", dependencies: [
      .product(name: "Algorithms", package: "swift-algorithms"),
-      .product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
      .product(name: "ArgumentParser", package: "swift-argument-parser"),
      .product(name: "Dynamic", package: "Dynamic"),
      .product(name: "SwiftDate", package: "SwiftDate"),
@@ -36,6 +39,11 @@ let package = Package(
      .product(name: "TextTable", package: "TextTable"),
      .product(name: "Sysctl", package: "swift-sysctl"),
      .product(name: "SwiftRadix", package: "SwiftRadix"),
+      .product(name: "Semaphore", package: "Semaphore"),
+      .product(name: "DMRetry", package: "swift-retry"),
+      .product(name: "XAttr", package: "swift-xattr"),
+      .product(name: "GRPC", package: "grpc-swift"),
+      .product(name: "Cirruslabs_TartGuestAgent_Grpc_Swift", package: "cirruslabs_tart-guest-agent_grpc_swift"),
    ], exclude: [
      "OCI/Reference/Makefile",
      "OCI/Reference/Reference.g4",
@@ -8,46 +8,32 @@ Built by CI engineers for your automation needs. Here are some highlights of Tar
 * Use Tart Packer Plugin to automate VM creation.
 * Easily integrates with any CI system.

-Tart powers [Cirrus Runners](https://tart.run/integrations/github-actions/?utm_source=github&utm_medium=referral)
+Tart powers [Cirrus Runners](https://cirrus-runners.app/)
 service — a drop-in replacement for the standard GitHub-hosted runners, offering 2-3 times better performance for a fraction of the price.

 <p align="center">
-  <a href="https://tart.run/integrations/github-actions/?utm_source=github&utm_medium=referral" target=_blank>
+  <a href="https://cirrus-runners.app/?utm_source=github&utm_medium=referral" target=_blank>
    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/CirrusRunnersForGHA.png" height="65"/>
  </a>
 </p>

-Tart is also adopted by several other automation services:
+Many companies are using Tart in their internal setups. Here are just a few of them:

 <p align="center">
-  <a href="https://cirrus-ci.org/guide/macOS/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/CirrusCI.png" height="65"/>
+  <a href="https://atlassian.com/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Atlassian.png" height="65"/>
  </a>
-  <a href="https://codemagic.io/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Codemagic.png" height="65"/>
-  </a>
-  <a href="https://testingbot.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/TestingBot.png" height="65"/>
-  </a>
-</p>
-
-Many more companies are using Tart in their internal setups. Here are a few of them:
-
-<p align="center">
-  <a href="https://ahrefs.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/ahrefs.png" height="65"/>
-  </a>
-  <a href="https://krisp.ai/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Krisp.png" height="65"/>
+  <a href="https://www.figma.com/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Figma.png" height="65"/>
  </a>
  <a href="https://mullvad.net/" target=_blank>
    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Mullvad.png" height="65"/>
  </a>
-  <a href="https://shape.dk/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/shape.png" height="65"/>
+  <a href="https://krisp.ai/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Krisp.png" height="65"/>
  </a>
-  <a href="https://suran.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Suran.png" height="65"/>
+  <a href="https://testingbot.com/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/TestingBot.png" height="65"/>
  </a>
  <a href="https://symflower.com/" target=_blank>
    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Symflower.png" height="65"/>
@@ -55,15 +41,18 @@ Many more companies are using Tart in their internal setups. Here are a few of t
  <a href="https://transloadit.com/" target=_blank>
    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Transloadit.png" height="65"/>
  </a>
-  <a href="https://uphold.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Uphold.png" height="65"/>
+  <a href="https://cirrus-ci.org/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/CirrusCI.png" height="65"/>
  </a>
  <a href="https://www.pitsdatarecovery.net/" target=_blank>
    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/PITSGlobalDataRecoveryServices.png" height="65"/>
  </a>
+  <a href="https://expo.dev/" target=_blank>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Expo.png" height="65"/>
+  </a>
 </p>

-**Note:** If your company or project is using Tart please consider [adding yourself to the list above](/Resources/Users/HowToAddYourself.md).
+**Note:** If your company or project is using Tart please consider [sharing with the community](https://github.com/cirruslabs/tart/discussions/857).

 <p align="center">
  <a href="https://aws.amazon.com/marketplace/pp/prodview-qczco34wlkdws?utm_source=github&utm_medium=referral" target=_blank>
@@ -77,8 +66,8 @@ Try running a Tart VM on your Apple Silicon device running macOS 13.0 (Ventura)

 ```bash
 brew install cirruslabs/cli/tart
-tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base
-tart run sonoma-base
+tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest sequoia-base
+tart run sequoia-base
 ```

 Please check the [official documentation](https://tart.run) for more information and/or feel free to use [discussions](https://github.com/cirruslabs/tart/discussions)
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key>
+	<string>Tart</string>
+	<key>CFBundleDisplayName</key>
+	<string>Tart</string>
+	<key>CFBundleIdentifier</key>
+	<string>org.cirruslabs.tart</string>
+	<key>CFBundleExecutable</key>
+	<string>tart</string>
+  <key>LSApplicationCategoryType</key>
+  <string>public.app-category.developer-tools</string>
+	<key>CFBundleIconFiles</key>
+	<array>
+		<string>AppIcon.png</string>
+	</array>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key>
+		<true/>
+	</dict>
+  <key>NSLocalNetworkUsageDescription</key>
+  <string>Access to OCI registries on the local network</string>
+</dict>
+</plist>
@@ -1,4 +0,0 @@
-If you'd like to highlight your use of Tart, please create a `456px` by `130px` logo and create a PR
-that adds it to `README.md` in alphabetical order. Don't forget to include a small description of your usage pattern.
-
-You can refer to `Background.png` as a base for your logo.
@@ -8,17 +8,15 @@ struct Clone: AsyncParsableCommand {
    discussion: """
    Creates a local virtual machine by cloning either a remote or another local virtual machine.

-    Due to copy-on-write magic in Apple File System a cloned VM won't actually claim all the space right away.
-    Only changes to a cloned disk will be written and claim new space. By default, Tart checks available capacity
-    in Tart's home directory and checks if there is enough space for the worst possible scenario: when the whole disk
-    will be modified.
+    Due to copy-on-write magic in Apple File System, a cloned VM won't actually claim all the space right away.
+    Only changes to a cloned disk will be written and claim new space. This also speeds up clones enormously.

-    This behaviour can be disabled by setting TART_NO_AUTO_PRUNE environment variable. This might be helpful
-    for use cases when the original image is very big and a workload is known to only modify a fraction of the cloned disk.
+    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the cloned image
+    to fit. This behaviour is called "automatic pruning" and can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
    """
  )

-  @Argument(help: "source VM name")
+  @Argument(help: "source VM name", completion: .custom(completeMachines))
  var sourceName: String

  @Argument(help: "new VM name")
@@ -30,6 +28,9 @@ struct Clone: AsyncParsableCommand {
  @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
  var concurrency: UInt = 4

+  @Flag(help: .hidden)
+  var deduplicate: Bool = false
+
  func validate() throws {
    if newName.contains("/") {
      throw ValidationError("<new-name> should be a local name")
@@ -47,7 +48,7 @@ struct Clone: AsyncParsableCommand {
    if let remoteName = try? RemoteName(sourceName), !ociStorage.exists(remoteName) {
      // Pull the VM in case it's OCI-based and doesn't exist locally yet
      let registry = try Registry(host: remoteName.host, namespace: remoteName.namespace, insecure: insecure)
-      try await ociStorage.pull(remoteName, registry: registry, concurrency: concurrency)
+      try await ociStorage.pull(remoteName, registry: registry, concurrency: concurrency, deduplicate: deduplicate)
    }

    let sourceVM = try VMStorageHelper.open(sourceName)
@@ -63,17 +64,21 @@ struct Clone: AsyncParsableCommand {
      try lock.lock()

      let generateMAC = try localStorage.hasVMsWithMACAddress(macAddress: sourceVM.macAddress())
-        && sourceVM.state() != "suspended"
+        && sourceVM.state() != .Suspended
      try sourceVM.clone(to: tmpVMDir, generateMAC: generateMAC)

      try localStorage.move(newName, from: tmpVMDir)

      try lock.unlock()

-      // APFS is doing copy-on-write so the above cloning operation (just copying files on disk)
+      // APFS is doing copy-on-write, so the above cloning operation (just copying files on disk)
      // is not actually claiming new space until the VM is started and it writes something to disk.
-      // So once we clone the VM let's try to claim a little bit of space for the VM to run.
-      try Prune.reclaimIfNeeded(UInt64(sourceVM.sizeBytes()), sourceVM)
+      //
+      // So, once we clone the VM let's try to claim the rest of space for the VM to run without errors.
+      let unallocatedBytes = try sourceVM.sizeBytes() - sourceVM.allocatedSizeBytes()
+      if unallocatedBytes > 0 {
+        try Prune.reclaimIfNeeded(UInt64(unallocatedBytes), sourceVM)
+      }
    }, onCancel: {
      try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
    })
@@ -1,7 +1,8 @@
 import ArgumentParser
 import Dispatch
-import SwiftUI
 import Foundation
+import SwiftUI
+import Virtualization

 struct Create: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Create a VM")
@@ -9,19 +10,24 @@ struct Create: AsyncParsableCommand {
  @Argument(help: "VM name")
  var name: String

-  @Option(help: ArgumentHelp("create a macOS VM using path to the IPSW file or URL (or \"latest\", to fetch the latest supported IPSW automatically)", valueName: "path"))
+  @Option(help: ArgumentHelp("create a macOS VM using path to the IPSW file or URL (or \"latest\", to fetch the latest supported IPSW automatically)", valueName: "path"), completion: .file())
  var fromIPSW: String?

  @Flag(help: "create a Linux VM")
  var linux: Bool = false

-  @Option(help: ArgumentHelp("Disk size in Gb")) 
+  @Option(help: ArgumentHelp("Disk size in GB"))
  var diskSize: UInt16 = 50

  func validate() throws {
    if fromIPSW == nil && !linux {
      throw ValidationError("Please specify either a --from-ipsw or --linux option!")
    }
+    #if arch(x86_64)
+      if fromIPSW != nil {
+        throw ValidationError("Only Linux VMs are supported on Intel!")
+      }
+    #endif
  }

  func run() async throws {
@@ -32,19 +38,29 @@ struct Create: AsyncParsableCommand {
    try tmpVMDirLock.lock()

    try await withTaskCancellationHandler(operation: {
-      if let fromIPSW = fromIPSW {
-        let ipswURL: URL
+      #if arch(arm64)
+        if let fromIPSW = fromIPSW {
+          let ipswURL: URL

-        if fromIPSW == "latest" {
-          ipswURL = try await VM.latestIPSWURL()
-        } else if fromIPSW.starts(with: "http://") || fromIPSW.starts(with: "https://") {
-          ipswURL = URL(string: fromIPSW)!
-        } else {
-          ipswURL = URL(fileURLWithPath: fromIPSW)
+          if fromIPSW == "latest" {
+            defaultLogger.appendNewLine("Looking up the latest supported IPSW...")
+
+            let image = try await withCheckedThrowingContinuation { continuation in
+              VZMacOSRestoreImage.fetchLatestSupported() { result in
+                continuation.resume(with: result)
+              }
+            }
+
+            ipswURL = image.url
+          } else if fromIPSW.starts(with: "http://") || fromIPSW.starts(with: "https://") {
+            ipswURL = URL(string: fromIPSW)!
+          } else {
+            ipswURL = URL(fileURLWithPath: NSString(string: fromIPSW).expandingTildeInPath)
+          }
+
+          _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize)
        }
-
-        _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize)
-      }
+      #endif

      if linux {
        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
@@ -5,7 +5,7 @@ import SwiftUI
 struct Delete: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Delete a VM")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeMachines))
  var name: [String]

  func run() async throws {
@@ -0,0 +1,168 @@
+import ArgumentParser
+import Foundation
+import NIOPosix
+import GRPC
+import Cirruslabs_TartGuestAgent_Grpc_Swift
+
+struct ExecCustomExitCodeError: Error {
+  let exitCode: Int32
+}
+
+struct Exec: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Execute a command in a running VM")
+
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
+  var name: String
+
+  @Flag(name: [.customShort("i")], help: "Attach host's standard input to a remote command")
+  var interactive: Bool = false
+
+  @Flag(name: [.customShort("t")], help: "Allocate a remote pseudo-terminal (PTY)")
+  var tty: Bool = false
+
+  @Argument(parsing: .captureForPassthrough, help: "Command to execute")
+  var command: [String]
+
+  func run() async throws {
+    // We only have withThrowingDiscardingTaskGroup available starting from macOS 14
+    if #unavailable(macOS 14) {
+      throw RuntimeError.Generic("\"tart exec\" is only available on macOS 14 (Sonoma) or newer")
+    }
+
+    // Open VM's directory
+    let vmDir = try VMStorageLocal().open(name)
+
+    // Ensure that the VM is running
+    if try !vmDir.running() {
+      throw RuntimeError.VMNotRunning(name)
+    }
+
+    // Create a gRPC channel connected to the VM's control socket
+    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    defer {
+      try! group.syncShutdownGracefully()
+    }
+
+    let channel = try GRPCChannelPool.with(
+      target: .unixDomainSocket(vmDir.controlSocketURL.path()),
+      transportSecurity: .plaintext,
+      eventLoopGroup: group,
+    )
+    defer {
+      try! channel.close().wait()
+    }
+
+    // Switch controlling terminal into raw mode when remote pseudo-terminal is requested
+    var state: State? = nil
+
+    if tty && Term.IsTerminal() {
+      state = try Term.MakeRaw()
+    }
+    defer {
+      // Restore terminal to its initial state
+      if let state {
+        try! Term.Restore(state)
+      }
+    }
+
+    // Execute a command in a running VM
+    let agentAsyncClient = AgentAsyncClient(channel: channel)
+    let execCall = agentAsyncClient.makeExecCall()
+
+    try await execCall.requestStream.send(.with {
+      $0.type = .command(.with {
+        $0.name = command[0]
+        $0.args = Array(command.dropFirst(1))
+        $0.interactive = interactive
+        $0.tty = tty
+        $0.terminalSize = .with {
+          let (width, height) = try! Term.GetSize()
+
+          $0.cols = UInt32(width)
+          $0.rows = UInt32(height)
+        }
+      })
+    })
+
+    // Process command events and optionally send our standard input and/or terminal dimensions
+    try await withThrowingTaskGroup { group in
+      // Stream host's standard input if interactive mode is enabled
+      if interactive {
+        let stdinStream = AsyncStream<Data> { continuation in
+          let handle = FileHandle.standardInput
+
+          handle.readabilityHandler = { handle in
+            let data = handle.availableData
+
+            continuation.yield(data)
+
+            if data.isEmpty {
+              continuation.finish()
+            }
+          }
+        }
+
+        group.addTask {
+          for await stdinData in stdinStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .standardInput(.with {
+                $0.data = stdinData
+              })
+            })
+          }
+        }
+      }
+
+      // Stream host's terminal dimensions if pseudo-terminal is requested
+      signal(SIGWINCH, SIG_IGN)
+      let sigwinchSrc = DispatchSource.makeSignalSource(signal: SIGWINCH)
+      sigwinchSrc.activate()
+
+      if tty {
+        let terminalDimensionsStream = AsyncStream { continuation in
+          sigwinchSrc.setEventHandler {
+            continuation.yield(try! Term.GetSize())
+          }
+        }
+
+        group.addTask {
+          for await (width, height) in terminalDimensionsStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .terminalResize(.with {
+                $0.cols = UInt32(width)
+                $0.rows = UInt32(height)
+              })
+            })
+          }
+        }
+      }
+
+      // Process command events
+      group.addTask {
+        for try await response in execCall.responseStream {
+          switch response.type {
+          case .standardOutput(let ioChunk):
+            try FileHandle.standardOutput.write(contentsOf: ioChunk.data)
+          case .standardError(let ioChunk):
+            try FileHandle.standardError.write(contentsOf: ioChunk.data)
+          case .exit(let exit):
+            throw ExecCustomExitCodeError(exitCode: exit.code)
+          default:
+            // Unknown event, do nothing
+            continue
+          }
+        }
+      }
+
+      while !group.isEmpty {
+        do {
+          try await group.next()
+        } catch {
+          group.cancelAll()
+
+          throw error
+        }
+      }
+    }
+  }
+}
@@ -4,10 +4,10 @@ import Foundation
 struct Export: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Export VM to a compressed .tvm file")

-  @Argument(help: "Source VM name.")
+  @Argument(help: "Source VM name.", completion: .custom(completeMachines))
  var name: String

-  @Argument(help: "Path to the destination file.")
+  @Argument(help: "Path to the destination file.", completion: .file())
  var path: String?

  func run() async throws {
@@ -0,0 +1,22 @@
+import ArgumentParser
+import Foundation
+import SystemConfiguration
+
+struct FQN: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Get a fully-qualified VM name", shouldDisplay: false)
+
+  @Argument(help: "VM name", completion: .custom(completeMachines))
+  var name: String
+
+  func run() async throws {
+    if var remoteName = try? RemoteName(name) {
+      let digest = try VMStorageOCI().digest(remoteName)
+
+      remoteName.reference = Reference(digest: digest)
+
+      print(remoteName)
+    } else {
+      print(name)
+    }
+  }
+}
@@ -2,9 +2,11 @@ import ArgumentParser
 import Foundation

 fileprivate struct VMInfo: Encodable {
+  let OS: OS
  let CPU: Int
  let Memory: UInt64
  let Disk: Int
+  let Size: String
  let Display: String
  let Running: Bool
  let State: String
@@ -13,7 +15,7 @@ fileprivate struct VMInfo: Encodable {
 struct Get: AsyncParsableCommand {
  static var configuration = CommandConfiguration(commandName: "get", abstract: "Get a VM's configuration")

-  @Argument(help: "VM name.")
+  @Argument(help: "VM name.", completion: .custom(completeLocalMachines))
  var name: String

  @Option(help: "Output format: text or json")
@@ -22,11 +24,9 @@ struct Get: AsyncParsableCommand {
  func run() async throws {
    let vmDir = try VMStorageLocal().open(name)
    let vmConfig = try VMConfig(fromURL: vmDir.configURL)
-    let diskSizeInGb = try vmDir.sizeGB()
    let memorySizeInMb = vmConfig.memorySize / 1024 / 1024

-    let info = VMInfo(CPU: vmConfig.cpuCount, Memory: memorySizeInMb, Disk: diskSizeInGb,
-                      Display: vmConfig.display.description, Running: try vmDir.running(), State: try vmDir.state())
+    let info = VMInfo(OS: vmConfig.os, CPU: vmConfig.cpuCount, Memory: memorySizeInMb, Disk: try vmDir.sizeGB(), Size: String(format: "%.3f", Float(try vmDir.allocatedSizeBytes()) / 1000 / 1000 / 1000), Display: vmConfig.display.description, Running: try vmDir.running(), State: try vmDir.state().rawValue)
    print(format.renderSingle(info))
  }
 }
@@ -13,7 +13,7 @@ enum IPResolutionStrategy: String, ExpressibleByArgument, CaseIterable {
 struct IP: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Get VM's IP address")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
  var name: String

  @Option(help: "Number of seconds to wait for a potential VM booting")
@@ -61,7 +61,7 @@ struct IP: AsyncParsableCommand {
          return ip
        }
      case .dhcp:
-        if let leases = try Leases(), let ip = try leases.ResolveMACAddress(macAddress: vmMACAddress) {
+        if let leases = try Leases(), let ip = leases.ResolveMACAddress(macAddress: vmMACAddress) {
          return ip
        }
      }
@@ -4,10 +4,10 @@ import Foundation
 struct Import: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Import VM from a compressed .tvm file")

-  @Argument(help: "Path to a file created with \"tart export\".")
+  @Argument(help: "Path to a file created with \"tart export\".", completion: .file())
  var path: String

-  @Argument(help: "Destination VM name.")
+  @Argument(help: "Destination VM name.", completion: .custom(completeLocalMachines))
  var name: String

  func validate() throws {
@@ -5,7 +5,9 @@ import SwiftUI
 fileprivate struct VMInfo: Encodable {
  let Source: String
  let Name: String
+  let Disk: Int
  let Size: Int
+  let SizeOnDisk: Int
  let Running: Bool
  let State: String
 }
@@ -16,7 +18,7 @@ struct List: AsyncParsableCommand {
  @Option(help: ArgumentHelp("Only display VMs from the specified source (e.g. --source local, --source oci)."))
  var source: String?

-  @Option(help: "Output format: text or json")
+  @Option(help: "Output format: text or json", completion: .list(["text", "json"]))
  var format: Format = .text

  @Flag(name: [.short, .long], help: ArgumentHelp("Only display VM names."))
@@ -37,13 +39,13 @@ struct List: AsyncParsableCommand {

    if source == nil || source == "local" {
      infos += sortedInfos(try VMStorageLocal().list().map { (name, vmDir) in
-        try VMInfo(Source: "local", Name: name, Size: vmDir.sizeGB(), Running: vmDir.running(), State: vmDir.state())
+        try VMInfo(Source: "local", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), SizeOnDisk: vmDir.allocatedSizeGB() - vmDir.deduplicatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue)
      })
    }

    if source == nil || source == "oci" {
      infos += sortedInfos(try VMStorageOCI().list().map { (name, vmDir, _) in
-        try VMInfo(Source: "oci", Name: name, Size: vmDir.sizeGB(), Running: vmDir.running(), State: vmDir.state())
+        try VMInfo(Source: "OCI", Name: name, Disk: vmDir.sizeGB(), Size: vmDir.allocatedSizeGB(), SizeOnDisk: vmDir.allocatedSizeGB() - vmDir.deduplicatedSizeGB(), Running: vmDir.running(), State: vmDir.state().rawValue)
      })
    }

@@ -49,9 +49,10 @@ struct Login: AsyncParsableCommand {
    ])

    if !noValidate {
+      let registry = try Registry(host: host, namespace: "", insecure: insecure,
+                                  credentialsProviders: [credentialsProvider])
+
      do {
-        let registry = try Registry(host: host, namespace: "", insecure: insecure,
-                                    credentialsProviders: [credentialsProvider])
        try await registry.ping()
      } catch {
        throw RuntimeError.InvalidCredentials("invalid credentials: \(error)")
@@ -7,7 +7,7 @@ import SwiftDate
 struct Prune: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Prune OCI and IPSW caches or local VMs")

-  @Option(help: ArgumentHelp("Entries to remove: \"caches\" targets OCI and IPSW caches and \"vms\" targets local VMs."))
+  @Option(help: ArgumentHelp("Entries to remove: \"caches\" targets OCI and IPSW caches and \"vms\" targets local VMs."), completion: .list(["caches", "vms"]))
  var entries: String = "caches"

  @Option(help: ArgumentHelp("Remove entries that were last accessed more than n days ago",
@@ -89,7 +89,7 @@ struct Prune: AsyncParsableCommand {
    var prunablesToDelete: [Prunable] = []

    for prunable in prunables {
-      let prunableSizeBytes = UInt64(try prunable.sizeBytes())
+      let prunableSizeBytes = UInt64(try prunable.allocatedSizeBytes())

      if prunableSizeBytes <= spaceBudgetBytes {
        // Don't mark for deletion as
@@ -158,7 +158,7 @@ struct Prune: AsyncParsableCommand {
      .sorted { try $0.accessDate() < $1.accessDate() }

    // Does it even make sense to start?
-    let cacheUsedBytes = try prunables.map { try $0.sizeBytes() }.reduce(0, +)
+    let cacheUsedBytes = try prunables.map { try $0.allocatedSizeBytes() }.reduce(0, +)
    if cacheUsedBytes < reclaimBytes {
      return
    }
@@ -177,9 +177,9 @@ struct Prune: AsyncParsableCommand {
        continue
      }

-      try SentrySDK.span?.setData(value: prunable.sizeBytes(), key: prunable.url.path)
+      try SentrySDK.span?.setData(value: prunable.allocatedSizeBytes(), key: prunable.url.path)

-      cacheReclaimedBytes += try prunable.sizeBytes()
+      cacheReclaimedBytes += try prunable.allocatedSizeBytes()

      try prunable.delete()
    }
@@ -9,8 +9,8 @@ struct Pull: AsyncParsableCommand {
    Pulls a virtual machine from a remote OCI-compatible registry. Supports authorization via Keychain (see "tart login --help"),
    Docker credential helpers defined in ~/.docker/config.json or via TART_REGISTRY_USERNAME/TART_REGISTRY_PASSWORD environment variables.

-    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the remote image to fit via "tart prune".
-    This behaviour can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
+    By default, Tart checks available capacity in Tart's home directory and tries to reclaim minimum possible storage for the remote image
+    to fit. This behaviour is called "automatic pruning" and can be disabled by setting TART_NO_AUTO_PRUNE environment variable.
    """
  )

@@ -23,6 +23,9 @@ struct Pull: AsyncParsableCommand {
  @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
  var concurrency: UInt = 4

+  @Flag(help: .hidden)
+  var deduplicate: Bool = false
+
  func validate() throws {
    if concurrency < 1 {
      throw ValidationError("network concurrency cannot be less than 1")
@@ -43,6 +46,6 @@ struct Pull: AsyncParsableCommand {

    defaultLogger.appendNewLine("pulling \(remoteName)...")

-    try await VMStorageOCI().pull(remoteName, registry: registry, concurrency: concurrency)
+    try await VMStorageOCI().pull(remoteName, registry: registry, concurrency: concurrency, deduplicate: deduplicate)
  }
 }
@@ -6,7 +6,7 @@ import Compression
 struct Push: AsyncParsableCommand {
  static var configuration = CommandConfiguration(abstract: "Push a VM to a registry")

-  @Argument(help: "local or remote VM name")
+  @Argument(help: "local or remote VM name", completion: .custom(completeMachines))
  var localName: String

  @Argument(help: "remote VM name(s)")
@@ -15,6 +15,9 @@ struct Push: AsyncParsableCommand {
  @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
  var insecure: Bool = false

+  @Option(help: "network concurrency to use when pushing a local VM to the OCI-compatible registry")
+  var concurrency: UInt = 4
+
  @Option(help: ArgumentHelp("chunk size in MB if registry supports chunked uploads",
                             discussion: """
                             By default monolithic method is used for uploading blobs to the registry but some registries support a more efficient chunked method.
@@ -23,6 +26,11 @@ struct Push: AsyncParsableCommand {
                             """))
  var chunkSize: Int = 0

+
+  @Option(name: [.customLong("label")], help: ArgumentHelp("additional metadata to attach to the OCI image configuration in key=value format",
+                                                           discussion: "Can be specified multiple times to attach multiple labels."))
+  var labels: [String] = []
+
  @Option(help: .hidden)
  var diskFormat: String = "v2"

@@ -33,6 +41,10 @@ struct Push: AsyncParsableCommand {
  func run() async throws {
    let ociStorage = VMStorageOCI()
    let localVMDir = try VMStorageHelper.open(localName)
+    let lock = try localVMDir.lock()
+    if try !lock.trylock() {
+      throw RuntimeError.VMIsRunning(localName)
+    }

    // Parse remote names supplied by the user
    let remoteNames = try remoteNames.map{
@@ -73,7 +85,9 @@ struct Push: AsyncParsableCommand {
          registry: registry,
          references: references,
          chunkSizeMb: chunkSize,
-          diskFormat: diskFormat
+          diskFormat: diskFormat,
+          concurrency: concurrency,
+          labels: parseLabels()
        )
        // Populate the local cache (if requested)
        if populateCache {
@@ -107,6 +121,28 @@ struct Push: AsyncParsableCommand {
    return RemoteName(host: registry.host!, namespace: registry.namespace,
                      reference: Reference(digest: digest))
  }
+
+  // Helper method to convert labels array to dictionary
+  func parseLabels() -> [String: String] {
+    var result = [String: String]()
+
+    for label in labels {
+      let parts = label.trimmingCharacters(in: .whitespaces).split(separator: "=", maxSplits: 1, omittingEmptySubsequences: false)
+
+      let key = parts.count > 0 ? String(parts[0]) : ""
+      let value = parts.count > 1 ? String(parts[1]) : ""
+
+      // It sometimes makes sense to provide an empty value,
+      // but not an empty key
+      if key.isEmpty {
+        continue
+      }
+
+      result[key] = value
+    }
+
+    return result
+  }  
 }

 extension Collection where Element == RemoteName {
@@ -2,9 +2,9 @@ import ArgumentParser
 import Foundation

 struct Rename: AsyncParsableCommand {
-  static var configuration = CommandConfiguration(abstract: "Rename a VM")
+  static var configuration = CommandConfiguration(abstract: "Rename a local VM")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
  var name: String

  @Argument(help: "new VM name")
@@ -20,11 +20,11 @@ struct Rename: AsyncParsableCommand {
    let localStorage = VMStorageLocal()

    if !localStorage.exists(name) {
-      throw ValidationError("failed to rename a non-existent VM: \(name)")
+      throw ValidationError("failed to rename a non-existent local VM: \(name)")
    }

    if localStorage.exists(newName) {
-      throw ValidationError("failed to rename VM \(name), target VM \(name) already exists, delete it first!")
+      throw ValidationError("failed to rename VM \(name), target VM \(newName) already exists, delete it first!")
    }

    try localStorage.rename(name, newName)
@@ -1,10 +1,11 @@
 import ArgumentParser
 import Foundation
+import Virtualization

 struct Set: AsyncParsableCommand {
  static var configuration = CommandConfiguration(commandName: "set", abstract: "Modify VM's configuration")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
  var name: String

  @Option(help: "Number of VM CPUs")
@@ -16,7 +17,24 @@ struct Set: AsyncParsableCommand {
  @Option(help: "VM display resolution in a format of <width>x<height>. For example, 1200x800")
  var display: VMDisplayConfig?

-  @Option(help: .hidden)
+  @Flag(inversion: .prefixedNo, help: ArgumentHelp("Whether to automatically reconfigure the VM's display to fit the window"))
+  var displayRefit: Bool? = nil
+
+  @Flag(help: ArgumentHelp("Generate a new random MAC address for the VM."))
+  var randomMAC: Bool = false
+
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp("Generate a new random serial number for the macOS VM."))
+  #endif
+  var randomSerial: Bool = false
+
+  @Option(help: ArgumentHelp("Replace the VM's disk contents with the disk contents at path.", valueName: "path"))
+  var disk: String?
+
+  @Option(help: ArgumentHelp("Resize the VMs disk to the specified size in GB (note that the disk size can only be increased to avoid losing data)",
+                             discussion: """
+                             See https://tart.run/faq/#disk-resizing for more details.
+                             """))
  var diskSize: UInt16?

  func run() async throws {
@@ -40,8 +58,28 @@ struct Set: AsyncParsableCommand {
      }
    }

+    vmConfig.displayRefit = displayRefit
+
+    if randomMAC {
+      vmConfig.macAddress = VZMACAddress.randomLocallyAdministered()
+    }
+
+    #if arch(arm64)
+      if randomSerial, let oldPlatform = vmConfig.platform as? Darwin {
+        vmConfig.platform = Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: oldPlatform.hardwareModel)
+      }
+    #endif
+
    try vmConfig.save(toURL: vmDir.configURL)

+    if let disk = disk {
+      let temporaryDiskURL = try Config().tartTmpDir.appendingPathComponent("set-disk-\(UUID().uuidString)")
+
+      try FileManager.default.copyItem(atPath: disk, toPath: temporaryDiskURL.path())
+
+      _ = try FileManager.default.replaceItemAt(vmDir.diskURL, withItemAt: temporaryDiskURL)
+    }
+
    if diskSize != nil {
      try vmDir.resizeDisk(diskSize!)
    }
@@ -6,7 +6,7 @@ import SwiftDate
 struct Stop: AsyncParsableCommand {
  static var configuration = CommandConfiguration(commandName: "stop", abstract: "Stop a VM")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeRunningMachines))
  var name: String

  @Option(name: [.short, .long], help: "Seconds to wait for graceful termination before forcefully terminating the VM")
@@ -15,12 +15,12 @@ struct Stop: AsyncParsableCommand {
  func run() async throws {
    let vmDir = try VMStorageLocal().open(name)
    switch try vmDir.state() {
-    case "suspended":
+    case .Suspended:
      try stopSuspended(vmDir)
-    case "running":
+    case .Running:
      try await stopRunning(vmDir)
-    default:
-      return
+    case .Stopped:
+      throw RuntimeError.VMNotRunning(name)
    }
  }

@@ -6,7 +6,7 @@ import SwiftDate
 struct Suspend: AsyncParsableCommand {
  static var configuration = CommandConfiguration(commandName: "suspend", abstract: "Suspend a VM")

-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeRunningMachines))
  var name: String

  func run() async throws {
@@ -14,7 +14,7 @@ struct Suspend: AsyncParsableCommand {
    let lock = try vmDir.lock()

    // Find the VM's PID
-    var pid = try lock.pid()
+    let pid = try lock.pid()
    if pid == 0 {
      throw RuntimeError.VMNotRunning("VM \"\(name)\" is not running")
    }
@@ -0,0 +1,89 @@
+import Foundation
+import Network
+import os.log
+import NIO
+import NIOPosix
+
+@available(macOS 14, *)
+class ControlSocket {
+  let controlSocketURL: URL
+  let vmPort: UInt32
+  let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+  let logger: os.Logger = os.Logger(subsystem: "org.cirruslabs.tart.control-socket", category: "network")
+
+  init(_ controlSocketURL: URL, vmPort: UInt32 = 8080) {
+    self.controlSocketURL = controlSocketURL
+    self.vmPort = vmPort
+  }
+
+  func run() async throws {
+    // Remove control socket file from previous "tart run" invocations,
+    // if any, otherwise we may get the "address already in use" error
+    try? FileManager.default.removeItem(atPath: controlSocketURL.path())
+
+    let serverChannel = try await ServerBootstrap(group: eventLoopGroup)
+      .bind(unixDomainSocketPath: controlSocketURL.path()) { childChannel in
+        childChannel.eventLoop.makeCompletedFuture {
+          return try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+            wrappingChannelSynchronously: childChannel
+          )
+        }
+      }
+
+    try await withThrowingDiscardingTaskGroup { group in
+      try await serverChannel.executeThenClose { serverInbound in
+        for try await clientChannel in serverInbound {
+          group.addTask {
+            try await self.handleClient(clientChannel)
+          }
+        }
+      }
+    }
+  }
+
+  func handleClient(_ clientChannel: NIOAsyncChannel<ByteBuffer, ByteBuffer>) async throws {
+    self.logger.info("received new control socket connection from a client")
+
+    try await clientChannel.executeThenClose { clientInbound, clientOutbound in
+      self.logger.info("dialing to VM on port \(self.vmPort)...")
+
+      do {
+        guard let vmConnection = try await vm?.connect(toPort: self.vmPort) else {
+          throw RuntimeError.VMSocketFailed(self.vmPort, "VM is not running")
+        }
+
+        self.logger.info("running control socket proxy")
+
+        let vmChannel = try await ClientBootstrap(group: eventLoopGroup).withConnectedSocket(vmConnection.fileDescriptor) { childChannel in
+          childChannel.eventLoop.makeCompletedFuture {
+            try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+              wrappingChannelSynchronously: childChannel
+            )
+          }
+        }
+
+        try await vmChannel.executeThenClose { (vmInbound, vmOutbound) in
+          try await withThrowingDiscardingTaskGroup { group in
+            // Proxy data from a client (e.g. "tart exec") to a VM
+            group.addTask {
+              for try await message in clientInbound {
+                try await vmOutbound.write(message)
+              }
+            }
+
+            // Proxy data from a VM to a client (e.g. "tart exec")
+            group.addTask {
+              for try await message in vmInbound {
+                try await clientOutbound.write(message)
+              }
+            }
+          }
+        }
+
+        self.logger.info("control socket client disconnected")
+      } catch (let error) {
+        self.logger.error("control socket connection failed: \(error)")
+      }
+    }
+  }
+}
@@ -36,12 +36,17 @@ class DockerConfigCredentialsProvider: CredentialsProvider {

    process.launch()

-    inPipe.fileHandleForWriting.write("\(host)\n".data(using: .utf8)!)
+    do {
+      try inPipe.fileHandleForWriting.write(contentsOf: "\(host)\n".data(using: .utf8)!)
+    } catch {
+      throw CredentialsProviderError.Failed(message: "Failed to write host to Docker helper!")
+    }
    inPipe.fileHandleForWriting.closeFile()

+    let outputData = try outPipe.fileHandleForReading.readToEnd()
+
    process.waitUntilExit()

-    let outputData = try outPipe.fileHandleForReading.readToEnd()
    if !(process.terminationReason == .exit && process.terminationStatus == 0) {
      if let outputData = outputData {
        print(String(decoding: outputData, as: UTF8.self))
@@ -41,7 +41,7 @@ class KeychainCredentialsProvider: CredentialsProvider {
                              kSecAttrLabel as String: "Tart Credentials",
    ]
    let value: [String: Any] = [kSecAttrAccount as String: user,
-                                kSecValueData as String: passwordData,
+                                kSecValueData as String: passwordData as Any,
    ]

    let status = SecItemCopyMatching(key as CFDictionary, nil)
@@ -1,56 +1,6 @@
 import Foundation
-import AsyncAlgorithms

-fileprivate let urlSession = createURLSession()
-
-class Fetcher {
-  static func fetch(_ request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    if viaFile {
-      return try await fetchViaFile(request)
-    }
-
-    return try await fetchViaMemory(request)
-  }
-
-  private static func fetchViaMemory(_ request: URLRequest) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    let dataCh = AsyncThrowingChannel<Data, Error>()
-
-    let (data, response) = try await urlSession.data(for: request)
-
-    Task {
-      await dataCh.send(data)
-
-      dataCh.finish()
-    }
-
-    return (dataCh, response as! HTTPURLResponse)
-  }
-
-  private static func fetchViaFile(_ request: URLRequest) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
-    let dataCh = AsyncThrowingChannel<Data, Error>()
-
-    let (fileURL, response) = try await urlSession.download(for: request)
-
-    // Acquire a handle to the downloaded file and then remove it.
-    //
-    // This keeps a working reference to that file, yet we don't
-    // have to deal with the cleanup any more.
-    let mappedFile = try Data(contentsOf: fileURL, options: [.alwaysMapped])
-    try FileManager.default.removeItem(at: fileURL)
-
-    Task {
-      for chunk in (0 ..< mappedFile.count).chunks(ofCount: 64 * 1024 * 1024) {
-        await dataCh.send(mappedFile.subdata(in: chunk))
-      }
-
-      dataCh.finish()
-    }
-
-    return (dataCh, response as! HTTPURLResponse)
-  }
-}
-
-fileprivate func createURLSession() -> URLSession {
+fileprivate var urlSession: URLSession = {
  let config = URLSessionConfiguration.default

  // Harbor expects a CSRF token to be present if the HTTP client
@@ -64,4 +14,84 @@ fileprivate func createURLSession() -> URLSession {
  config.httpShouldSetCookies = false

  return URLSession(configuration: config)
+}()
+
+class Fetcher {
+  static func fetch(_ request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
+    let task = urlSession.dataTask(with: request)
+
+    let delegate = Delegate()
+    task.delegate = delegate
+
+    let stream = AsyncThrowingStream<Data, Error> { continuation in
+      delegate.streamContinuation = continuation
+    }
+
+    let response = try await withCheckedThrowingContinuation { continuation in
+      delegate.responseContinuation = continuation
+      task.resume()
+    }
+
+    return (stream, response as! HTTPURLResponse)
+  }
+}
+
+fileprivate class Delegate: NSObject, URLSessionDataDelegate {
+  var responseContinuation: CheckedContinuation<URLResponse, Error>?
+  var streamContinuation: AsyncThrowingStream<Data, Error>.Continuation?
+
+  private var buffer: Data = Data()
+  private let bufferFlushSize = 16 * 1024 * 1024
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive response: URLResponse,
+    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+  ) {
+    // Soft-limit for the maximum buffer capacity
+    let capacity = min(response.expectedContentLength, Int64(bufferFlushSize))
+
+    // Pre-initialize buffer as we now know the capacity
+    buffer = Data(capacity: Int(capacity))
+
+    responseContinuation?.resume(returning: response)
+    responseContinuation = nil
+    completionHandler(.allow)
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive data: Data
+  ) {
+    buffer.append(data)
+
+    if buffer.count >= bufferFlushSize {
+      streamContinuation?.yield(buffer)
+      buffer.removeAll(keepingCapacity: true)
+    }
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    didCompleteWithError error: Error?
+  ) {
+    if let error = error {
+      responseContinuation?.resume(throwing: error)
+      responseContinuation = nil
+
+      streamContinuation?.finish(throwing: error)
+      streamContinuation = nil
+    } else {
+      if !buffer.isEmpty {
+        streamContinuation?.yield(buffer)
+        buffer.removeAll(keepingCapacity: true)
+      }
+
+      streamContinuation?.finish()
+      streamContinuation = nil
+    }
+  }
 }
@@ -0,0 +1,57 @@
+import Foundation
+
+struct LocalLayerCache {
+  struct DigestInfo {
+    let range: Range<Data.Index>
+    let compressedDigest: String
+    let uncompressedContentDigest: String?
+  }
+
+  let name: String
+  let deduplicatedBytes: UInt64
+  let diskURL: URL
+
+  private let mappedDisk: Data
+  private var digestToRange: [String: DigestInfo] = [:]
+  private var offsetToRange: [UInt64: DigestInfo] = [:]
+
+  init?(_ name: String, _ deduplicatedBytes: UInt64, _ diskURL: URL, _ manifest: OCIManifest) throws {
+    self.name = name
+    self.deduplicatedBytes = deduplicatedBytes
+    self.diskURL = diskURL
+
+    // mmap(2) the disk that contains the layers from the manifest
+    self.mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
+
+    // Record the ranges of the disk layers listed in the manifest
+    var offset: UInt64 = 0
+
+    for layer in manifest.layers.filter({ $0.mediaType == diskV2MediaType }) {
+      guard let uncompressedSize = layer.uncompressedSize() else {
+        return nil
+      }
+
+      let info = DigestInfo(
+        range: Int(offset)..<Int(offset + uncompressedSize),
+        compressedDigest: layer.digest,
+        uncompressedContentDigest: layer.uncompressedContentDigest()!
+      )
+      self.digestToRange[layer.digest] = info
+      self.offsetToRange[offset] = info
+
+      offset += uncompressedSize
+    }
+  }
+
+  func findInfo(digest: String, offsetHint: UInt64) -> DigestInfo? {
+    // Layers can have the same digests, for example, empty ones. Let's use the offset hint to make a better guess.
+    if let info = self.offsetToRange[offsetHint], info.compressedDigest == digest {
+      return info
+    }
+    return self.digestToRange[digest]
+  }
+
+  func subdata(_ range: Range<Data.Index>) -> Data {
+    return self.mappedDisk.subdata(in: range)
+  }
+}
@@ -52,6 +52,11 @@ struct ARPCache {
    process.standardInput = FileHandle.nullDevice

    try process.run()
+
+    guard let arpCommandOutput = try pipe.fileHandleForReading.readToEnd() else {
+      throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
+    }
+
    process.waitUntilExit()

    if !(process.terminationReason == .exit && process.terminationStatus == 0) {
@@ -60,10 +65,6 @@ struct ARPCache {
        terminationStatus: process.terminationStatus)
    }

-    guard let arpCommandOutput = try pipe.fileHandleForReading.readToEnd() else {
-      throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
-    }
-
    self.arpCommandOutput = arpCommandOutput
  }

@@ -45,7 +45,10 @@ class Leases {
      (lease.mac, lease)
    })

-    self.leases = Dictionary(uniqueKeysWithValues: leases)
+    self.leases = Dictionary(leases) { (left, right) in
+      // When duplicate lease is found, prefer a newer lease over the older one
+      (left.expiresAt > right.expiresAt) ? left : right
+    }
  }

  /// Parse leases from the host cache similarly to the PLCache_read() function found in Apple's Open Source releases.
@@ -1,7 +1,8 @@
 import Virtualization
+import Semaphore

 protocol Network {
  func attachments() -> [VZNetworkDeviceAttachment]
-  func run(_ sema: DispatchSemaphore) throws
+  func run(_ sema: AsyncSemaphore) throws
  func stop() async throws
 }
@@ -1,4 +1,5 @@
 import Foundation
+import Semaphore
 import Virtualization

 class NetworkBridged: Network {
@@ -12,7 +13,7 @@ class NetworkBridged: Network {
    interfaces.map { VZBridgedNetworkDeviceAttachment(interface: $0) }
  }

-  func run(_ sema: DispatchSemaphore) throws {
+  func run(_ sema: AsyncSemaphore) throws {
    // no-op, only used for Softnet
  }

@@ -1,4 +1,5 @@
 import Foundation
+import Semaphore
 import Virtualization

 class NetworkShared: Network {
@@ -6,7 +7,7 @@ class NetworkShared: Network {
    [VZNATNetworkDeviceAttachment()]
  }

-  func run(_ sema: DispatchSemaphore) throws {
+  func run(_ sema: AsyncSemaphore) throws {
    // no-op, only used for Softnet
  }

@@ -1,7 +1,8 @@
-import Foundation
-import Virtualization
 import Atomics
+import Foundation
+import Semaphore
 import System
+import Virtualization

 enum SoftnetError: Error {
  case InitializationFailed(why: String)
@@ -15,7 +16,7 @@ class Softnet: Network {

  let vmFD: Int32

-  init(vmMACAddress: String) throws {
+  init(vmMACAddress: String, extraArguments: [String] = []) throws {
    let fds = UnsafeMutablePointer<Int32>.allocate(capacity: MemoryLayout<Int>.stride * 2)

    let ret = socketpair(AF_UNIX, SOCK_DGRAM, 0, fds)
@@ -30,7 +31,7 @@ class Softnet: Network {
    try setSocketBuffers(softnetFD, 1 * 1024 * 1024);

    process.executableURL = try Self.softnetExecutableURL()
-    process.arguments = ["--vm-fd", String(STDIN_FILENO), "--vm-mac-address", vmMACAddress]
+    process.arguments = ["--vm-fd", String(STDIN_FILENO), "--vm-mac-address", vmMACAddress] + extraArguments
    process.standardInput = FileHandle(fileDescriptor: softnetFD, closeOnDealloc: false)
  }

@@ -44,7 +45,7 @@ class Softnet: Network {
    return executableURL
  }

-  func run(_ sema: DispatchSemaphore) throws {
+  func run(_ sema: AsyncSemaphore) throws {
    try process.run()

    monitorTask = Task {
@@ -1,6 +1,6 @@
 import Foundation

 protocol Disk {
-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, progress: Progress) async throws -> [OCIManifestLayer]
-  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress) async throws
+  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer]
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache?, deduplicate: Bool) async throws
 }
@@ -5,7 +5,7 @@ class DiskV1: Disk {
  private static let bufferSizeBytes = 4 * 1024 * 1024
  private static let layerLimitBytes = 500 * 1000 * 1000

-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, progress: Progress) async throws -> [OCIManifestLayer] {
+  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer] {
    var pushedLayers: [OCIManifestLayer] = []

    // Open the disk file
@@ -45,7 +45,7 @@ class DiskV1: Disk {
    return pushedLayers
  }

-  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress) async throws {
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil, deduplicate: Bool = false) async throws {
    if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
      throw OCIError.FailedToCreateVmFile
    }
@@ -57,7 +57,7 @@ class DiskV1: Disk {
    // Decompress the layers onto the disk in a single stream
    let filter = try OutputFilter(.decompress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { data in
      if let data = data {
-        disk.write(data)
+        try disk.write(contentsOf: data)
      }
    }

@@ -1,48 +1,104 @@
 import Foundation
 import Compression
+import System
+import Retry

 class DiskV2: Disk {
  private static let bufferSizeBytes = 4 * 1024 * 1024
-  private static let layerLimitBytes = 500 * 1000 * 1000
-  private static let holeGranularityBytes = 64 * 1024
+  private static let layerLimitBytes = 512 * 1024 * 1024

-  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, progress: Progress) async throws -> [OCIManifestLayer] {
-    var pushedLayers: [OCIManifestLayer] = []
+  // A zero chunk for faster than byte-by-byte comparisons
+  //
+  // Assumes that the other Data(...) is equal in size, but it's fine to get a false-negative
+  // on the last block since it costs only 4 MiB of excess data per 512 MiB layer.
+  //
+  // Some simple benchmarks ("sync && sudo purge" command was used to negate the disk caching effects):
+  // +--------------------------------------+---------------------------------------------------+
+  // | Operation                            | time(1) result                                    |
+  // +--------------------------------------+---------------------------------------------------+
+  // | Data(...) == zeroChunk               | 2.16s user 11.71s system 73% cpu 18.928 total     |
+  // | Data(...).contains(where: {$0 != 0}) | 603.68s user 12.97s system 99% cpu 10:22.85 total |
+  // +--------------------------------------+---------------------------------------------------+
+  private static let holeGranularityBytes = 4 * 1024 * 1024
+  private static let zeroChunk = Data(count: holeGranularityBytes)
+
+  static func push(diskURL: URL, registry: Registry, chunkSizeMb: Int, concurrency: UInt, progress: Progress) async throws -> [OCIManifestLayer] {
+    var pushedLayers: [(index: Int, pushedLayer: OCIManifestLayer)] = []

    // Open the disk file
-    var mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
+    let mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])

    // Compress the disk file as multiple individually decompressible streams,
-    // each equal ``Self.layerLimitBytes`` bytes or slightly larger due to the
-    // internal compressor's buffer
-    var offset: UInt64 = 0
+    // each equal ``Self.layerLimitBytes`` bytes or less due to LZ4 compression
+    try await withThrowingTaskGroup(of: (Int, OCIManifestLayer).self) { group in
+      for (index, data) in mappedDisk.chunks(ofCount: layerLimitBytes).enumerated() {
+        // Respect the concurrency limit
+        if index >= concurrency {
+          if let (index, pushedLayer) = try await group.next() {
+            pushedLayers.append((index, pushedLayer))
+          }
+        }

-    while let (compressedData, uncompressedSize, uncompressedDigest) = try compressNextLayerOfLimitBytesOrMore(mappedDisk: mappedDisk, offset: offset) {
-      offset += uncompressedSize
+        // Launch a disk layer pushing task
+        group.addTask {
+          let compressedData = try (data as NSData).compressed(using: .lz4) as Data
+          let compressedDataDigest = Digest.hash(compressedData)

-      let layerDigest = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb)
+          try await retry(maxAttempts: 5) {
+            if try await !registry.blobExists(compressedDataDigest) {
+              _ = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb, digest: compressedDataDigest)
+            }
+          } recoverFromFailure: { error in
+            if error is URLError {
+              print("Error: \(error.localizedDescription)")
+              print("Attempting to re-try...")

-      pushedLayers.append(OCIManifestLayer(
-        mediaType: diskV2MediaType,
-        size: compressedData.count,
-        digest: layerDigest,
-        uncompressedSize: uncompressedSize,
-        uncompressedContentDigest: uncompressedDigest
-      ))
+              return .retry
+            }

-      // Update progress using a relative value
-      progress.completedUnitCount += Int64(uncompressedSize)
+            return .throw
+          }
+
+          // Update progress using a relative value
+          progress.completedUnitCount += Int64(data.count)
+
+          return (index, OCIManifestLayer(
+            mediaType: diskV2MediaType,
+            size: compressedData.count,
+            digest: compressedDataDigest,
+            uncompressedSize: UInt64(data.count),
+            uncompressedContentDigest: Digest.hash(data)
+          ))
+        }
+      }
+
+      for try await pushedLayer in group {
+        pushedLayers.append(pushedLayer)
+      }
    }

-    return pushedLayers
+    return pushedLayers.sorted {
+      $0.index < $1.index
+    }.map {
+      $0.pushedLayer
+    }
  }

-  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress) async throws {
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil, deduplicate: Bool = false) async throws {
    // Support resumable pulls
    let pullResumed = FileManager.default.fileExists(atPath: diskURL.path)

-    if !pullResumed && !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
-      throw OCIError.FailedToCreateVmFile
+    if !pullResumed {
+      if deduplicate, let localLayerCache = localLayerCache {
+        // Clone the local layer cache's disk and use it as a base, potentially
+        // reducing the space usage since some blocks won't be written at all
+        try FileManager.default.copyItem(at: localLayerCache.diskURL, to: diskURL)
+      } else {
+        // Otherwise create an empty disk
+        if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
+          throw OCIError.FailedToCreateVmFile
+        }
+      }
    }

    // Calculate the uncompressed disk size
@@ -62,6 +118,15 @@ class DiskV2: Disk {
    try disk.truncate(atOffset: uncompressedDiskSize)
    try disk.close()

+    // Determine the file system block size
+    var st = stat()
+    if stat(diskURL.path, &st) == -1 {
+      let details = Errno(rawValue: errno)
+
+      throw RuntimeError.PullFailed("failed to stat(2) disk \(diskURL.path): \(details)")
+    }
+    let fsBlockSize = UInt64(st.st_blksize)
+
    // Concurrently fetch and decompress layers
    try await withThrowingTaskGroup(of: Void.self) { group in
      var globalDiskWritingOffset: UInt64 = 0
@@ -86,29 +151,52 @@ class DiskV2: Disk {
        // Launch a fetching and decompression task
        group.addTask {
          // No need to fetch and decompress anything if we've already done so
-          if try pullResumed && Digest.hash(diskURL, offset: diskWritingOffset, size: uncompressedLayerSize) == uncompressedLayerContentDigest {
+          if pullResumed {
+            // do not check hash in the condition above to make it lazy e.g. only do expensive calculations if needed
+            if try Digest.hash(diskURL, offset: diskWritingOffset, size: uncompressedLayerSize) == uncompressedLayerContentDigest {
+              // Update the progress
+              progress.completedUnitCount += Int64(diskLayer.size)
+
+              return
+            }
+          }
+
+          // Open the disk file for writing
+          let disk = try FileHandle(forWritingTo: diskURL)
+
+          // Also open the disk file for reading and verifying
+          // its contents in case the local layer cache is used
+          let rdisk: FileHandle? = if deduplicate && localLayerCache != nil {
+            try FileHandle(forReadingFrom: diskURL)
+          } else {
+            nil
+          }
+
+          // Check if we already have this layer contents in the local layer cache,
+          // or perhaps even on the cloned disk (when the deduplication is enabled)
+          if let localLayerCache = localLayerCache,
+             let localLayerInfo = localLayerCache.findInfo(digest: diskLayer.digest, offsetHint: diskWritingOffset),
+             localLayerInfo.uncompressedContentDigest == uncompressedLayerContentDigest {
+            if deduplicate && localLayerInfo.range.lowerBound == diskWritingOffset {
+              // Do nothing, because the data is already on the disk that we've inherited from
+            } else {
+              // Fulfil the layer contents from the local blob cache
+              let data = localLayerCache.subdata(localLayerInfo.range)
+              _ = try zeroSkippingWrite(disk, rdisk, fsBlockSize, diskWritingOffset, data)
+            }
+
+            try disk.close()
+
+            if let rdisk = rdisk {
+              try rdisk.close()
+            }
+
            // Update the progress
            progress.completedUnitCount += Int64(diskLayer.size)

            return
          }

-          // Open the disk file
-          let disk = try FileHandle(forWritingTo: diskURL)
-
-          // A zero chunk for faster than byte-by-byte comparisons
-          //
-          // Assumes that the other Data(...) is equal in size, but it's fine to get a false-negative
-          // on the last block since it costs only 64 KiB of excess data per 500 MB layer.
-          //
-          // Some simple benchmarks ("sync && sudo purge" command was used to negate the disk caching effects):
-          // +--------------------------------------+---------------------------------------------------+
-          // | Operation                            | time(1) result                                    |
-          // +--------------------------------------+---------------------------------------------------+
-          // | Data(...) == zeroChunk               | 2.16s user 11.71s system 73% cpu 18.928 total     |
-          // | Data(...).contains(where: {$0 != 0}) | 603.68s user 12.97s system 99% cpu 10:22.85 total |
-          // +--------------------------------------+---------------------------------------------------+
-          let zeroChunk = Data(count: holeGranularityBytes)
          var diskWritingOffset = diskWritingOffset

          // Pull and decompress a single layer into the specific offset on disk
@@ -117,27 +205,38 @@ class DiskV2: Disk {
              return
            }

-            for chunk in data.chunks(ofCount: holeGranularityBytes) {
-              // Only write chunks that are not zero
-              if chunk != zeroChunk {
-                try disk.seek(toOffset: diskWritingOffset)
-                disk.write(chunk)
-              }
-
-              diskWritingOffset += UInt64(chunk.count)
-            }
+            diskWritingOffset = try zeroSkippingWrite(disk, rdisk, fsBlockSize, diskWritingOffset, data)
          }

-          try await registry.pullBlob(diskLayer.digest) { data in
-            try filter.write(data)
+          var rangeStart: Int64 = 0

-            // Update the progress
-            progress.completedUnitCount += Int64(data.count)
+          try await retry(maxAttempts: 5) {
+            try await registry.pullBlob(diskLayer.digest, rangeStart: rangeStart) { data in
+              try filter.write(data)
+
+              // Update the progress
+              progress.completedUnitCount += Int64(data.count)
+
+              // Update the current range start
+              rangeStart += Int64(data.count)
+            }
+          } recoverFromFailure: { error in
+            if error is URLError {
+              print("Error pulling disk layer \(index + 1): \"\(error.localizedDescription)\", attempting to re-try...")
+
+              return .retry
+            }
+
+            return .throw
          }

          try filter.finalize()

          try disk.close()
+
+          if let rdisk = rdisk {
+            try rdisk.close()
+          }
        }

        globalDiskWritingOffset += uncompressedLayerSize
@@ -145,44 +244,50 @@ class DiskV2: Disk {
    }
  }

-  private static func compressNextLayerOfLimitBytesOrMore(mappedDisk: Data, offset: UInt64) throws -> (Data, UInt64, String)? {
-    var compressedData = Data()
-    var bytesRead: UInt64 = 0
-    let digest = Digest()
+  private static func zeroSkippingWrite(_ disk: FileHandle, _ rdisk: FileHandle?, _ fsBlockSize: UInt64, _ offset: UInt64, _ data: Data) throws -> UInt64 {
+    var offset = offset

-    // Create a compressing filter that we will terminate upon
-    // reaching ``Self.layerLimitBytes`` of compressed data
-    let compressingFilter = try InputFilter(.compress, using: .lz4, bufferCapacity: bufferSizeBytes) { (length: Int) -> Data? in
-      if compressedData.count >= Self.layerLimitBytes {
-        return nil
+    for chunk in data.chunks(ofCount: holeGranularityBytes) {
+      // If the local layer cache is used, only write chunks that differ
+      // since the base disk can contain anything at any position
+      if let rdisk = rdisk {
+        // F_PUNCHHOLE requires the holes to be aligned to file system block boundaries
+        let isHoleAligned = (offset % fsBlockSize) == 0 && (UInt64(chunk.count) % fsBlockSize) == 0
+
+        if isHoleAligned && chunk == zeroChunk {
+          var arg = fpunchhole_t(fp_flags: 0, reserved: 0, fp_offset: off_t(offset), fp_length: off_t(chunk.count))
+
+          if fcntl(disk.fileDescriptor, F_PUNCHHOLE, &arg) == -1 {
+            let details = Errno(rawValue: errno)
+
+            throw RuntimeError.PullFailed("failed to punch hole: \(details)")
+          }
+        } else {
+          try rdisk.seek(toOffset: offset)
+          let actualContentsOnDisk = try rdisk.read(upToCount: chunk.count)
+
+          if chunk != actualContentsOnDisk {
+            try disk.seek(toOffset: offset)
+            try disk.write(contentsOf: chunk)
+          }
+        }
+
+        offset += UInt64(chunk.count)
+
+        continue
      }

-      let readFromByte = Int(offset + bytesRead)
-
-      let numBytesToRead = min(mappedDisk.count - readFromByte, bufferSizeBytes)
-      if numBytesToRead == 0 {
-        return nil
+      // Otherwise, only write chunks that are not zero
+      // since the base disk is created from scratch and
+      // is zeroed via truncate(2)
+      if chunk != zeroChunk {
+        try disk.seek(toOffset: offset)
+        try disk.write(contentsOf: chunk)
      }

-      let uncompressedChunk = mappedDisk.subdata(in: readFromByte ..< (readFromByte + numBytesToRead))
-
-      bytesRead += UInt64(uncompressedChunk.count)
-      digest.update(uncompressedChunk)
-
-      return uncompressedChunk
+      offset += UInt64(chunk.count)
    }

-    // Retrieve compressed data chunks, but normally no more than ``Self.layerLimitBytes`` bytes
-    while let compressedChunk = try compressingFilter.readData(ofLength: Self.bufferSizeBytes) {
-      compressedData.append(compressedChunk)
-    }
-
-    // Nothing was read this time from the disk,
-    // signal that to the consumer
-    if bytesRead == 0 {
-      return nil
-    }
-
-    return (compressedData, bytesRead, digest.finalize())
+    return offset
  }
 }
@@ -66,6 +66,11 @@ struct OCIManifest: Codable, Equatable {
 struct OCIConfig: Codable {
  var architecture: Architecture = .arm64
  var os: OS = .darwin
+  var config: ConfigContainer?
+
+  struct ConfigContainer: Codable {
+    var Labels: [String: String]?
+  }

  func toJSON() throws -> Data {
    try Config.jsonEncoder().encode(self)
@@ -78,7 +83,7 @@ struct OCIManifestConfig: Codable, Equatable {
  var digest: String
 }

-struct OCIManifestLayer: Codable, Equatable {
+struct OCIManifestLayer: Codable, Equatable, Hashable {
  var mediaType: String
  var size: Int
  var digest: String
@@ -113,6 +118,14 @@ struct OCIManifestLayer: Codable, Equatable {
  func uncompressedContentDigest() -> String? {
    annotations?[uncompressedContentDigestAnnotation]
  }
+
+  static func == (lhs: Self, rhs: Self) -> Bool {
+    return lhs.digest == rhs.digest
+  }
+
+  func hash(into hasher: inout Hasher) {
+    hasher.combine(digest)
+  }
 }

 struct Descriptor: Equatable {
@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2

 import Antlr4

@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4

 open class ReferenceLexer: Lexer {
@@ -49,7 +49,7 @@ open class ReferenceLexer: Lexer {

 	public
 	required init(_ input: CharStream) {
-	    RuntimeMetaData.checkVersion("4.11.1", RuntimeMetaData.VERSION)
+	    RuntimeMetaData.checkVersion("4.13.2", RuntimeMetaData.VERSION)
 		super.init(input)
 		_interp = LexerATNSimulator(self, ReferenceLexer._ATN, ReferenceLexer._decisionToDFA, ReferenceLexer._sharedContextCache)
 	}
@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4

 /**
@@ -1,4 +1,4 @@
-// Generated from java-escape by ANTLR 4.11.1
+// Generated from Reference.g4 by ANTLR 4.13.2
 import Antlr4

 open class ReferenceParser: Parser {
@@ -41,7 +41,7 @@ open class ReferenceParser: Parser {
 	static let VOCABULARY = Vocabulary(_LITERAL_NAMES, _SYMBOLIC_NAMES)

 	override open
-	func getGrammarFileName() -> String { return "java-escape" }
+	func getGrammarFileName() -> String { return "Reference.g4" }

 	override open
 	func getRuleNames() -> [String] { return ReferenceParser.ruleNames }
@@ -60,7 +60,7 @@ open class ReferenceParser: Parser {

 	override public
 	init(_ input:TokenStream) throws {
-	    RuntimeMetaData.checkVersion("4.11.1", RuntimeMetaData.VERSION)
+	    RuntimeMetaData.checkVersion("4.13.2", RuntimeMetaData.VERSION)
 		try super.init(input)
 		_interp = ParserATNSimulator(self,ReferenceParser._ATN,ReferenceParser._decisionToDFA, ReferenceParser._sharedContextCache)
 	}
@@ -460,7 +460,7 @@ open class ReferenceParser: Parser {
 		 		setState(63)
 		 		try _errHandler.sync(self)
 		 		_la = try _input.LA(1)
-		 		if ((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0) {
+		 		if (((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
 		 			setState(62)
 		 			try separator()

@@ -611,7 +611,7 @@ open class ReferenceParser: Parser {
 		 	setState(84)
 		 	try _errHandler.sync(self)
 		 	_la = try _input.LA(1)
-		 	while ((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0) {
+		 	while (((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
 		 		setState(79)
 		 		try separator()
 		 		setState(80)
@@ -664,7 +664,7 @@ open class ReferenceParser: Parser {
 		 	try enterOuterAlt(_localctx, 1)
 		 	setState(87)
 		 	_la = try _input.LA(1)
-		 	if (!((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0)) {
+		 	if (!(((Int64(_la) & ~0x3f) == 0 && ((Int64(1) << _la) & 88) != 0))) {
 		 	try _errHandler.recoverInline(self)
 		 	}
 		 	else {
@@ -1,6 +1,5 @@
 import Foundation
 import Algorithms
-import AsyncAlgorithms

 enum RegistryError: Error {
  case UnexpectedHTTPStatusCode(when: String, code: Int, details: String = "")
@@ -10,6 +9,7 @@ enum RegistryError: Error {
 }

 enum HTTPMethod: String {
+  case HEAD = "HEAD"
  case GET = "GET"
  case POST = "POST"
  case PUT = "PUT"
@@ -20,21 +20,35 @@ enum HTTPCode: Int {
  case Ok = 200
  case Created = 201
  case Accepted = 202
+  case PartialContent = 206
  case Unauthorized = 401
+  case NotFound = 404
 }

 extension Data {
  func asText() -> String {
    String(decoding: self, as: UTF8.self)
  }
+
+  func asTextPreview(limit: Int = 1000) -> String {
+    guard count > limit else {
+      return asText()
+    }
+
+    return "\(asText().prefix(limit))..."
+  }
 }

-extension AsyncThrowingChannel<Data, Error> {
-  func asData() async throws -> Data {
+extension AsyncThrowingStream<Data, Error> {
+  func asData(limitBytes: Int64? = nil) async throws -> Data {
    var result = Data()

    for try await chunk in self {
      result += chunk
+
+      if let limitBytes, result.count > limitBytes {
+        return result
+      }
    }

    return result
@@ -42,9 +56,6 @@ extension AsyncThrowingChannel<Data, Error> {
 }

 struct TokenResponse: Decodable, Authentication {
-  let defaultIssuedAt = Date()
-  let defaultExpiresIn = 60
-
  var token: String?
  var accessToken: String?
  var expiresIn: Int?
@@ -66,7 +77,8 @@ struct TokenResponse: Decodable, Authentication {
      return dateFormatter.date(from: dateString) ?? Date()
    }

-    let response = try decoder.decode(TokenResponse.self, from: fromData)
+    var response = try decoder.decode(TokenResponse.self, from: fromData)
+    response.issuedAt = response.issuedAt ?? Date()

    guard response.token != nil || response.accessToken != nil else {
      throw DecodingError.keyNotFound(CodingKeys.token, .init(codingPath: [], debugDescription: "Missing token or access_token. One must be present."))
@@ -85,7 +97,7 @@ struct TokenResponse: Decodable, Authentication {
      //
      // [1]: https://docs.docker.com/registry/spec/auth/token/#requesting-a-token

-      (issuedAt ?? defaultIssuedAt) + TimeInterval(expiresIn ?? defaultExpiresIn)
+      (issuedAt ?? Date()) + TimeInterval(expiresIn ?? 60)
    }
  }

@@ -114,11 +126,11 @@ class Registry {
    return host
  }

-  init(urlComponents: URLComponents,
+  init(baseURL: URL,
       namespace: String,
       credentialsProviders: [CredentialsProvider] = [EnvironmentCredentialsProvider(), DockerConfigCredentialsProvider(), KeychainCredentialsProvider()]
  ) throws {
-    baseURL = urlComponents.url!
+    self.baseURL = baseURL
    self.namespace = namespace
    self.credentialsProviders = credentialsProviders
  }
@@ -132,7 +144,17 @@ class Registry {
    let proto = insecure ? "http" : "https"
    let baseURLComponents = URLComponents(string: proto + "://" + host + "/v2/")!

-    try self.init(urlComponents: baseURLComponents, namespace: namespace, credentialsProviders: credentialsProviders)
+    guard let baseURL = baseURLComponents.url else {
+      var hint = ""
+
+      if host.hasPrefix("http://") || host.hasPrefix("https://") {
+        hint += ", make sure that it doesn't start with http:// or https://"
+      }
+
+      throw RuntimeError.ImproperlyFormattedHost(host, hint)
+    }
+
+    try self.init(baseURL: baseURL, namespace: namespace, credentialsProviders: credentialsProviders)
  }

  func ping() async throws {
@@ -150,7 +172,7 @@ class Registry {
                                                 body: manifestJSON)
    if response.statusCode != HTTPCode.Created.rawValue {
      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing manifest", code: response.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
    }

    return Digest.hash(manifestJSON)
@@ -161,7 +183,7 @@ class Registry {
                                                 headers: ["Accept": ociManifestMediaType])
    if response.statusCode != HTTPCode.Ok.rawValue {
      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling manifest", code: response.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
    }

    let manifest = try OCIManifest(fromJSON: data)
@@ -181,19 +203,19 @@ class Registry {
    return URLComponents(url: uploadLocation.absolutize(baseURL), resolvingAgainstBaseURL: true)!
  }

-  public func pushBlob(fromData: Data, chunkSizeMb: Int = 0) async throws -> String {
+  public func pushBlob(fromData: Data, chunkSizeMb: Int = 0, digest: String? = nil) async throws -> String {
    // Initiate a blob upload
    let (data, postResponse) = try await dataRequest(.POST, endpointURL("\(namespace)/blobs/uploads/"),
                                                     headers: ["Content-Length": "0"])
    if postResponse.statusCode != HTTPCode.Accepted.rawValue {
      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (POST)", code: postResponse.statusCode,
-                                                   details: data.asText())
+                                                   details: data.asTextPreview())
    }

    // Figure out where to upload the blob
    var uploadLocation = try uploadLocationFromResponse(postResponse)

-    let digest = Digest.hash(fromData)
+    let digest = digest ?? Digest.hash(fromData)

    if chunkSizeMb == 0 {
      // monolithic upload
@@ -208,7 +230,7 @@ class Registry {
      )
      if response.statusCode != HTTPCode.Created.rawValue {
        throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (PUT) to \(uploadLocation)",
-                                                     code: response.statusCode, details: data.asText())
+                                                     code: response.statusCode, details: data.asTextPreview())
      }
      return digest
    }
@@ -231,7 +253,7 @@ class Registry {
      // always accept both statuses since AWS ECR is not following specification
      if response.statusCode != HTTPCode.Created.rawValue && response.statusCode != HTTPCode.Accepted.rawValue {
        throw RegistryError.UnexpectedHTTPStatusCode(when: "streaming blob to \(uploadLocation)",
-                                                     code: response.statusCode, details: data.asText())
+                                                     code: response.statusCode, details: data.asTextPreview())
      }
      uploadedBytes += chunk.count
      // Update location for the next chunk
@@ -241,10 +263,35 @@ class Registry {
    return digest
  }

-  public func pullBlob(_ digest: String, handler: (Data) async throws -> Void) async throws {
-    let (channel, response) = try await channelRequest(.GET, endpointURL("\(namespace)/blobs/\(digest)"), viaFile: true)
-    if response.statusCode != HTTPCode.Ok.rawValue {
-      let body = try await channel.asData().asText()
+  public func blobExists(_ digest: String) async throws -> Bool {
+    let (data, response) = try await dataRequest(.HEAD, endpointURL("\(namespace)/blobs/\(digest)"))
+
+    switch response.statusCode {
+    case HTTPCode.Ok.rawValue:
+      return true
+    case HTTPCode.NotFound.rawValue:
+      return false
+    default:
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "checking blob", code: response.statusCode, details: data.asTextPreview())
+    }
+  }
+
+  public func pullBlob(_ digest: String, rangeStart: Int64 = 0, handler: (Data) async throws -> Void) async throws {
+    var expectedStatusCode = HTTPCode.Ok
+    var headers: [String: String] = [:]
+
+    // Send Range header and expect HTTP 206 in return
+    //
+    // However, do not send Range header at all when rangeStart is 0,
+    // because it makes no sense and we might get HTTP 200 in return
+    if rangeStart != 0 {
+      expectedStatusCode = HTTPCode.PartialContent
+      headers["Range"] = "bytes=\(rangeStart)-"
+    }
+
+    let (channel, response) = try await channelRequest(.GET, endpointURL("\(namespace)/blobs/\(digest)"), headers: headers, viaFile: true)
+    if response.statusCode != expectedStatusCode.rawValue {
+      let body = try await channel.asData(limitBytes: 4096).asTextPreview()
      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling blob", code: response.statusCode,
                                                   details: body)
    }
@@ -284,7 +331,7 @@ class Registry {
    body: Data? = nil,
    doAuth: Bool = true,
    viaFile: Bool = false
-  ) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  ) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
    var urlComponents = urlComponents

    if urlComponents.queryItems == nil && !parameters.isEmpty {
@@ -304,12 +351,11 @@ class Registry {
      request.httpBody = body
    }

-    var (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile)
+    var (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile, doAuth: doAuth)

    if doAuth && response.statusCode == HTTPCode.Unauthorized.rawValue {
-      _ = try await channel.asData()
      try await auth(response: response)
-      (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile)
+      (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile, doAuth: doAuth)
    }

    return (channel, response)
@@ -369,7 +415,7 @@ class Registry {
    let (data, response) = try await dataRequest(.GET, authenticateURL, headers: headers, doAuth: false)
    if response.statusCode != HTTPCode.Ok.rawValue {
      throw RegistryError.AuthFailed(why: "received unexpected HTTP status code \(response.statusCode) "
-        + "while retrieving an authentication token", details: data.asText())
+        + "while retrieving an authentication token", details: data.asTextPreview())
    }

    await authenticationKeeper.set(try TokenResponse.parse(fromData: data))
@@ -390,11 +436,13 @@ class Registry {
    return nil
  }

-  private func authAwareRequest(request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  private func authAwareRequest(request: URLRequest, viaFile: Bool = false, doAuth: Bool) async throws -> (AsyncThrowingStream<Data, Error>, HTTPURLResponse) {
    var request = request

-    if let (name, value) = await authenticationKeeper.header() {
-      request.addValue(value, forHTTPHeaderField: name)
+    if doAuth {
+      if let (name, value) = await authenticationKeeper.header() {
+        request.addValue(value, forHTTPHeaderField: name)
+      }
    }

    request.setValue("Tart/\(CI.version) (\(DeviceInfo.os); \(DeviceInfo.model))",
@@ -11,7 +11,7 @@ class PIDLock {
    if fd == -1 {
      let details = Errno(rawValue: CInt(errno))

-      throw RuntimeError.PIDLockFailed("failed to open lock file \(url): \(details)")
+      throw RuntimeError.PIDLockMissing("failed to open lock file \(url): \(details)")
    }
  }

@@ -6,127 +6,140 @@ struct UnsupportedHostOSError: Error, CustomStringConvertible {
  }
 }

-struct Darwin: PlatformSuspendable {
-  var ecid: VZMacMachineIdentifier
-  var hardwareModel: VZMacHardwareModel
+#if arch(arm64)

-  init(ecid: VZMacMachineIdentifier, hardwareModel: VZMacHardwareModel) {
-    self.ecid = ecid
-    self.hardwareModel = hardwareModel
-  }
+  struct Darwin: PlatformSuspendable {
+    var ecid: VZMacMachineIdentifier
+    var hardwareModel: VZMacHardwareModel

-  init(from decoder: Decoder) throws {
-    let container = try decoder.container(keyedBy: CodingKeys.self)
-
-    let encodedECID = try container.decode(String.self, forKey: .ecid)
-    guard let data = Data.init(base64Encoded: encodedECID) else {
-      throw DecodingError.dataCorruptedError(forKey: .ecid,
-                                             in: container,
-                                             debugDescription: "failed to initialize Data using the provided value")
-    }
-    guard let ecid = VZMacMachineIdentifier.init(dataRepresentation: data) else {
-      throw DecodingError.dataCorruptedError(forKey: .ecid,
-                                             in: container,
-                                             debugDescription: "failed to initialize VZMacMachineIdentifier using the provided value")
-    }
-    self.ecid = ecid
-
-    let encodedHardwareModel = try container.decode(String.self, forKey: .hardwareModel)
-    guard let data = Data.init(base64Encoded: encodedHardwareModel) else {
-      throw DecodingError.dataCorruptedError(forKey: .hardwareModel, in: container, debugDescription: "")
-    }
-    guard let hardwareModel = VZMacHardwareModel.init(dataRepresentation: data) else {
-      throw DecodingError.dataCorruptedError(forKey: .hardwareModel, in: container, debugDescription: "")
-    }
-    self.hardwareModel = hardwareModel
-  }
-
-  func encode(to encoder: Encoder) throws {
-    var container = encoder.container(keyedBy: CodingKeys.self)
-
-    try container.encode(ecid.dataRepresentation.base64EncodedString(), forKey: .ecid)
-    try container.encode(hardwareModel.dataRepresentation.base64EncodedString(), forKey: .hardwareModel)
-  }
-
-  func os() -> OS {
-    .darwin
-  }
-
-  func bootLoader(nvramURL: URL) throws -> VZBootLoader {
-    VZMacOSBootLoader()
-  }
-
-  func platform(nvramURL: URL) throws -> VZPlatformConfiguration {
-    let result = VZMacPlatformConfiguration()
-
-    result.machineIdentifier = ecid
-    result.auxiliaryStorage = VZMacAuxiliaryStorage(url: nvramURL)
-
-    if !hardwareModel.isSupported {
-      // At the moment support of M1 chip is not yet dropped in any macOS version
-      // This mean that host software is not supporting this hardware model and should be updated
-      throw UnsupportedHostOSError()
+    init(ecid: VZMacMachineIdentifier, hardwareModel: VZMacHardwareModel) {
+      self.ecid = ecid
+      self.hardwareModel = hardwareModel
    }

-    result.hardwareModel = hardwareModel
+    init(from decoder: Decoder) throws {
+      let container = try decoder.container(keyedBy: CodingKeys.self)

-    return result
-  }
+      let encodedECID = try container.decode(String.self, forKey: .ecid)
+      guard let data = Data.init(base64Encoded: encodedECID) else {
+        throw DecodingError.dataCorruptedError(forKey: .ecid,
+                                               in: container,
+                                               debugDescription: "failed to initialize Data using the provided value")
+      }
+      guard let ecid = VZMacMachineIdentifier.init(dataRepresentation: data) else {
+        throw DecodingError.dataCorruptedError(forKey: .ecid,
+                                               in: container,
+                                               debugDescription: "failed to initialize VZMacMachineIdentifier using the provided value")
+      }
+      self.ecid = ecid

-  func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
-    let result = VZMacGraphicsDeviceConfiguration()
+      let encodedHardwareModel = try container.decode(String.self, forKey: .hardwareModel)
+      guard let data = Data.init(base64Encoded: encodedHardwareModel) else {
+        throw DecodingError.dataCorruptedError(forKey: .hardwareModel, in: container, debugDescription: "")
+      }
+      guard let hardwareModel = VZMacHardwareModel.init(dataRepresentation: data) else {
+        throw UnsupportedHostOSError()
+      }
+      self.hardwareModel = hardwareModel
+    }
+
+    func encode(to encoder: Encoder) throws {
+      var container = encoder.container(keyedBy: CodingKeys.self)
+
+      try container.encode(ecid.dataRepresentation.base64EncodedString(), forKey: .ecid)
+      try container.encode(hardwareModel.dataRepresentation.base64EncodedString(), forKey: .hardwareModel)
+    }
+
+    func os() -> OS {
+      .darwin
+    }
+
+    func bootLoader(nvramURL: URL) throws -> VZBootLoader {
+      VZMacOSBootLoader()
+    }
+
+    func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration {
+      if needsNestedVirtualization {
+        throw RuntimeError.VMConfigurationError("macOS virtual machines do not support nested virtualization")
+      }
+
+      let result = VZMacPlatformConfiguration()
+
+      result.machineIdentifier = ecid
+      result.auxiliaryStorage = VZMacAuxiliaryStorage(url: nvramURL)
+
+      if !hardwareModel.isSupported {
+        // At the moment support of M1 chip is not yet dropped in any macOS version
+        // This mean that host software is not supporting this hardware model and should be updated
+        throw UnsupportedHostOSError()
+      }
+
+      result.hardwareModel = hardwareModel
+
+      return result
+    }
+
+    func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
+      let result = VZMacGraphicsDeviceConfiguration()
+
+      if let hostMainScreen = NSScreen.main {
+        let vmScreenSize = NSSize(width: vmConfig.display.width, height: vmConfig.display.height)
+        result.displays = [
+          VZMacGraphicsDisplayConfiguration(for: hostMainScreen, sizeInPoints: vmScreenSize)
+        ]
+
+        return result
+      }

-    if let hostMainScreen = NSScreen.main {
-      let vmScreenSize = NSSize(width: vmConfig.display.width, height: vmConfig.display.height)
      result.displays = [
-        VZMacGraphicsDisplayConfiguration(for: hostMainScreen, sizeInPoints: vmScreenSize)
+        VZMacGraphicsDisplayConfiguration(
+          widthInPixels: vmConfig.display.width,
+          heightInPixels: vmConfig.display.height,
+          // A reasonable guess according to Apple's documentation[1]
+          // [1]: https://developer.apple.com/documentation/coregraphics/1456599-cgdisplayscreensize
+          pixelsPerInch: 72
+        )
      ]

      return result
    }

-    result.displays = [
-      VZMacGraphicsDisplayConfiguration(
-        widthInPixels: vmConfig.display.width,
-        heightInPixels: vmConfig.display.height,
-        // A reasonable guess according to Apple's documentation[1]
-        // [1]: https://developer.apple.com/documentation/coregraphics/1456599-cgdisplayscreensize
-        pixelsPerInch: 72
-      )
-    ]
+    func keyboards() -> [VZKeyboardConfiguration] {
+      if #available(macOS 14, *) {
+        // Mac keyboard is only supported by guests starting with macOS Ventura
+        return [VZUSBKeyboardConfiguration(), VZMacKeyboardConfiguration()]
+      } else {
+        return [VZUSBKeyboardConfiguration()]
+      }
+    }

-    return result
-  }
+    func keyboardsSuspendable() -> [VZKeyboardConfiguration] {
+      if #available(macOS 14, *) {
+        return [VZMacKeyboardConfiguration()]
+      } else {
+        // fallback to the regular configuration
+        return keyboards()
+      }
+    }

-  func keyboards() -> [VZKeyboardConfiguration] {
-    if #available(macOS 14, *) {
-      // Mac keyboard is only supported by guests starting with macOS Ventura
-      return [VZMacKeyboardConfiguration(), VZUSBKeyboardConfiguration()]
-    } else {
-      return [VZUSBKeyboardConfiguration()]
+    func pointingDevices() -> [VZPointingDeviceConfiguration] {
+      // Trackpad is only supported by guests starting with macOS Ventura
+      [VZUSBScreenCoordinatePointingDeviceConfiguration(), VZMacTrackpadConfiguration()]
+    }
+
+    func pointingDevicesSimplified() -> [VZPointingDeviceConfiguration] {
+      // Only include the USB pointing device, not the trackpad
+      return [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+    }
+
+    func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration] {
+      if #available(macOS 14, *) {
+        return [VZMacTrackpadConfiguration()]
+      } else {
+        // fallback to the regular configuration
+        return pointingDevices()
+      }
    }
  }

-  func keyboardsSuspendable() -> [VZKeyboardConfiguration] {
-    if #available(macOS 14, *) {
-      return [VZMacKeyboardConfiguration()]
-    } else {
-      // fallback to the regular configuration
-      return keyboards()
-    }
-  }
-
-  func pointingDevices() -> [VZPointingDeviceConfiguration] {
-    // Trackpad is only supported by guests starting with macOS Ventura
-    [VZMacTrackpadConfiguration(), VZUSBScreenCoordinatePointingDeviceConfiguration()]
-  }
-
-  func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration] {
-    if #available(macOS 14, *) {
-      return [VZMacTrackpadConfiguration()]
-    } else {
-      // fallback to the regular configuration
-      return pointingDevices()
-    }
-  }
-}
+#endif
@@ -14,8 +14,12 @@ struct Linux: Platform {
    return result
  }

-  func platform(nvramURL: URL) throws -> VZPlatformConfiguration {
-    VZGenericPlatformConfiguration()
+  func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration {
+    let config = VZGenericPlatformConfiguration()
+    if #available(macOS 15, *) {
+      config.isNestedVirtualizationEnabled = needsNestedVirtualization
+    }
+    return config
  }

  func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
@@ -38,4 +42,9 @@ struct Linux: Platform {
  func pointingDevices() -> [VZPointingDeviceConfiguration] {
    [VZUSBScreenCoordinatePointingDeviceConfiguration()]
  }
+
+  func pointingDevicesSimplified() -> [VZPointingDeviceConfiguration] {
+    // Linux doesn't support trackpad, so just return the regular pointing devices
+    return pointingDevices()
+  }
 }
@@ -3,10 +3,11 @@ import Virtualization
 protocol Platform: Codable {
  func os() -> OS
  func bootLoader(nvramURL: URL) throws -> VZBootLoader
-  func platform(nvramURL: URL) throws -> VZPlatformConfiguration
+  func platform(nvramURL: URL, needsNestedVirtualization: Bool) throws -> VZPlatformConfiguration
  func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration
  func keyboards() -> [VZKeyboardConfiguration]
  func pointingDevices() -> [VZPointingDeviceConfiguration]
+  func pointingDevicesSimplified() -> [VZPointingDeviceConfiguration]
 }

 protocol PlatformSuspendable: Platform {
@@ -8,5 +8,8 @@ protocol Prunable {
  var url: URL { get }
  func delete() throws
  func accessDate() throws -> Date
+  // size on disk as seen in Finder including empty blocks
  func sizeBytes() throws -> Int
+  // actual size on disk without empty blocks
+  func allocatedSizeBytes() throws -> Int
 }
@@ -18,6 +18,7 @@ struct Root: AsyncParsableCommand {
      Login.self,
      Logout.self,
      IP.self,
+      Exec.self,
      Pull.self,
      Push.self,
      Import.self,
@@ -26,6 +27,7 @@ struct Root: AsyncParsableCommand {
      Rename.self,
      Stop.self,
      Delete.self,
+      FQN.self,
    ])

  public static func main() async throws {
@@ -49,6 +51,10 @@ struct Root: AsyncParsableCommand {
    }
    defer { SentrySDK.flush(timeout: 2.seconds.timeInterval) }

+    SentrySDK.configureScope { scope in
+      scope.setExtra(value: ProcessInfo.processInfo.arguments, key: "Command-line arguments")
+    }
+
    // Enrich future events with Cirrus CI-specific tags
    if let tags = ProcessInfo.processInfo.environment["CIRRUS_SENTRY_TAGS"] {
      SentrySDK.configureScope { scope in
@@ -96,6 +102,11 @@ struct Root: AsyncParsableCommand {
        try command.run()
      }
    } catch {
+      // Not an error, just a custom exit code from "tart exec"
+      if let execCustomExitCodeError = error as? ExecCustomExitCodeError {
+        Foundation.exit(execCustomExitCodeError.exitCode)
+      }
+
      // Capture the error into Sentry
      SentrySDK.capture(error: error)
      SentrySDK.flush(timeout: 2.seconds.timeInterval)
@@ -0,0 +1,28 @@
+import Foundation
+
+fileprivate func normalizeName(_ name: String) -> String {
+  // Colons are misinterpreted by Zsh completion
+  return name.replacingOccurrences(of: ":", with: "\\:")
+}
+
+func completeMachines(_ arguments: [String]) -> [String] {
+  let localVMs = (try? VMStorageLocal().list().map { name, _ in
+    normalizeName(name)
+  }) ?? []
+  let ociVMs = (try? VMStorageOCI().list().map { name, _, _ in
+    normalizeName(name)
+  }) ?? []
+  return (localVMs + ociVMs)
+}
+
+func completeLocalMachines(_ arguments: [String]) -> [String] {
+  let localVMs = (try? VMStorageLocal().list()) ?? []
+  return localVMs.map { name, _ in normalizeName(name) }
+}
+
+func completeRunningMachines(_ arguments: [String]) -> [String] {
+  let localVMs = (try? VMStorageLocal().list()) ?? []
+  return localVMs
+    .filter { _, vmDir in (try? vmDir.state() == .Running) ?? false}
+    .map { name, _ in normalizeName(name) }
+}
@@ -0,0 +1,60 @@
+import Foundation
+import System
+
+struct State {
+  fileprivate let termios: termios
+}
+
+class Term {
+  static func IsTerminal() -> Bool {
+    var termios = termios()
+
+    return tcgetattr(FileHandle.standardInput.fileDescriptor, &termios) != -1
+  }
+
+  static func MakeRaw() throws -> State {
+    var termiosOrig = termios()
+
+    var ret = tcgetattr(FileHandle.standardInput.fileDescriptor, &termiosOrig)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to retrieve terminal parameters: \(details)")
+    }
+
+    var termiosRaw = termiosOrig
+    cfmakeraw(&termiosRaw)
+
+    ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termiosRaw)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+
+    return State(termios: termiosOrig)
+  }
+
+  static func Restore(_ state: State) throws {
+    var termios = state.termios
+
+    let ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termios)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+  }
+
+  static func GetSize() throws -> (width: UInt16, height: UInt16) {
+    var winsize = winsize()
+
+    guard ioctl(STDOUT_FILENO, TIOCGWINSZ, &winsize) != -1 else {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to get terminal size: \(details)")
+    }
+
+    return (width: winsize.ws_col, height: winsize.ws_row)
+  }
+}
@@ -1,4 +1,5 @@
 import Foundation
+import System

 extension URL {
  func accessDate() throws -> Date {
@@ -13,7 +14,9 @@ extension URL {
    let times = [accessDate.asTimeval(), modificationDate.asTimeval()]
    let ret = utimes(path, times)
    if ret != 0 {
-      throw RuntimeError.FailedToUpdateAccessDate("utimes(2) failed: \(ret.explanation())")
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.FailedToUpdateAccessDate("utimes(2) failed: \(details)")
    }
  }
 }
@@ -1,4 +1,5 @@
 import Foundation
+import XAttr

 extension URL: Prunable {
  var url: URL {
@@ -9,7 +10,35 @@ extension URL: Prunable {
    try FileManager.default.removeItem(at: self)
  }

-  func sizeBytes() throws -> Int {
+  func allocatedSizeBytes() throws -> Int {
    try resourceValues(forKeys: [.totalFileAllocatedSizeKey]).totalFileAllocatedSize!
  }
+
+  func deduplicatedSizeBytes() throws -> Int {
+    let values = try resourceValues(forKeys: [.totalFileAllocatedSizeKey, .mayShareFileContentKey])
+    // make sure the file's origin file is there and duplication works
+    if values.mayShareFileContent == true {
+      return Int(deduplicatedBytes())
+    }
+    return 0
+  }
+
+  func sizeBytes() throws -> Int {
+    try resourceValues(forKeys: [.totalFileSizeKey]).totalFileSize!
+  }
+
+  func setDeduplicatedBytes(_ size: UInt64) {
+    let data = "\(size)".data(using: .utf8)!
+    try! self.setExtendedAttribute(name: "run.tart.deduplicated-bytes", value: data)
+  }
+
+  func deduplicatedBytes() -> UInt64 {
+    guard let data = try? self.extendedAttributeValue(forName: "run.tart.deduplicated-bytes") else {
+      return 0
+    }
+    if let strValue = String(data: data, encoding: .utf8) {
+      return UInt64(strValue) ?? 0
+    }
+    return 0
+  }
 }
@@ -1,6 +1,6 @@
 import Foundation
 import Virtualization
-import AsyncAlgorithms
+import Semaphore

 struct UnsupportedRestoreImageError: Error {
 }
@@ -30,7 +30,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
  var configuration: VZVirtualMachineConfiguration

  // Semaphore used to communicate with the VZVirtualMachineDelegate
-  var sema = DispatchSemaphore(value: 0)
+  var sema = AsyncSemaphore(value: 0)

  // VM's config
  var name: String
@@ -45,7 +45,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
       directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
       serialPorts: [VZSerialPortConfiguration] = [],
-       suspendable: Bool = false
+       suspendable: Bool = false,
+       nested: Bool = false,
+       audio: Bool = true,
+       clipboard: Bool = true,
+       sync: VZDiskImageSynchronizationMode = .full,
+       caching: VZDiskImageCachingMode? = nil,
+       noTrackpad: Bool = false
  ) throws {
    name = vmDir.name
    config = try VMConfig.init(fromURL: vmDir.configURL)
@@ -61,7 +67,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
                                                network: network, additionalStorageDevices: additionalStorageDevices,
                                                directorySharingDevices: directorySharingDevices,
                                                serialPorts: serialPorts,
-                                                suspendable: suspendable
+                                                suspendable: suspendable,
+                                                nested: nested,
+                                                audio: audio,
+                                                clipboard: clipboard,
+                                                sync: sync,
+                                                caching: caching,
+                                                noTrackpad: noTrackpad
    )
    virtualMachine = VZVirtualMachine(configuration: configuration)

@@ -89,12 +101,14 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    // Download the IPSW
    defaultLogger.appendNewLine("Fetching \(remoteURL.lastPathComponent)...")

-    let (channel, response) = try await Fetcher.fetch(URLRequest(url: remoteURL), viaFile: true)
+    let request = URLRequest(url: remoteURL)
+    let (channel, response) = try await Fetcher.fetch(request, viaFile: true)
+
+    let temporaryLocation = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString + ".ipsw")

    let progress = Progress(totalUnitCount: response.expectedContentLength)
    ProgressObserver(progress).log(defaultLogger)

-    let temporaryLocation = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString + ".ipsw")
    FileManager.default.createFile(atPath: temporaryLocation.path, contents: nil)
    let lock = try FileLock(lockURL: temporaryLocation)
    try lock.lock()
@@ -103,9 +117,8 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    let digest = Digest()

    for try await chunk in channel {
-      let chunkAsData = Data(chunk)
-      fileHandle.write(chunkAsData)
-      digest.update(chunkAsData)
+      try fileHandle.write(contentsOf: chunk)
+      digest.update(chunk)
      progress.completedUnitCount += Int64(chunk.count)
    }

@@ -116,18 +129,6 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    return try FileManager.default.replaceItemAt(finalLocation, withItemAt: temporaryLocation)!
  }

-  static func latestIPSWURL() async throws -> URL {
-    defaultLogger.appendNewLine("Looking up the latest supported IPSW...")
-
-    let image = try await withCheckedThrowingContinuation { continuation in
-      VZMacOSRestoreImage.fetchLatestSupported() { result in
-        continuation.resume(with: result)
-      }
-    }
-
-    return image.url
-  }
-
  var inFinalState: Bool {
    get {
      virtualMachine.state == VZVirtualMachine.State.stopped ||
@@ -137,82 +138,90 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    }
  }

-  init(
-    vmDir: VMDirectory,
-    ipswURL: URL,
-    diskSizeGB: UInt16,
-    network: Network = NetworkShared(),
-    additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
-    directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
-    serialPorts: [VZSerialPortConfiguration] = []
-  ) async throws {
-    var ipswURL = ipswURL
+  #if arch(arm64)
+    init(
+      vmDir: VMDirectory,
+      ipswURL: URL,
+      diskSizeGB: UInt16,
+      network: Network = NetworkShared(),
+      additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
+      directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
+      serialPorts: [VZSerialPortConfiguration] = []
+    ) async throws {
+      var ipswURL = ipswURL

-    if !ipswURL.isFileURL {
-      ipswURL = try await VM.retrieveIPSW(remoteURL: ipswURL)
-    }
-
-    // We create a temporary TART_HOME directory in tests, which has its "cache" folder symlinked
-    // to the users Tart cache directory (~/.tart/cache). However, the Virtualization.Framework
-    // cannot deal with paths that contain symlinks, so expand them here first.
-    ipswURL.resolveSymlinksInPath()
-
-    // Load the restore image and try to get the requirements
-    // that match both the image and our platform
-    let image = try await withCheckedThrowingContinuation { continuation in
-      VZMacOSRestoreImage.load(from: ipswURL) { result in
-        continuation.resume(with: result)
+      if !ipswURL.isFileURL {
+        ipswURL = try await VM.retrieveIPSW(remoteURL: ipswURL)
      }
-    }

-    guard let requirements = image.mostFeaturefulSupportedConfiguration else {
-      throw UnsupportedRestoreImageError()
-    }
+      // We create a temporary TART_HOME directory in tests, which has its "cache" folder symlinked
+      // to the users Tart cache directory (~/.tart/cache). However, the Virtualization.Framework
+      // cannot deal with paths that contain symlinks, so expand them here first.
+      ipswURL.resolveSymlinksInPath()

-    // Create NVRAM
-    _ = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)
-
-    // Create disk
-    try vmDir.resizeDisk(diskSizeGB)
-
-    name = vmDir.name
-    // Create config
-    config = VMConfig(
-      platform: Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: requirements.hardwareModel),
-      cpuCountMin: requirements.minimumSupportedCPUCount,
-      memorySizeMin: requirements.minimumSupportedMemorySize
-    )
-    // allocate at least 4 CPUs because otherwise VMs are frequently freezing
-    try config.setCPU(cpuCount: max(4, requirements.minimumSupportedCPUCount))
-    try config.save(toURL: vmDir.configURL)
-
-    // Initialize the virtual machine and its configuration
-    self.network = network
-    configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, nvramURL: vmDir.nvramURL,
-                                                vmConfig: config, network: network,
-                                                additionalStorageDevices: additionalStorageDevices,
-                                                directorySharingDevices: directorySharingDevices,
-                                                serialPorts: serialPorts
-    )
-    virtualMachine = VZVirtualMachine(configuration: configuration)
-
-    super.init()
-    virtualMachine.delegate = self
-
-    // Run automated installation
-    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
-      DispatchQueue.main.async { [ipswURL] in
-        let installer = VZMacOSInstaller(virtualMachine: self.virtualMachine, restoringFromImageAt: ipswURL)
-
-        defaultLogger.appendNewLine("Installing OS...")
-        ProgressObserver(installer.progress).log(defaultLogger)
-
-        installer.install { result in
+      // Load the restore image and try to get the requirements
+      // that match both the image and our platform
+      let image = try await withCheckedThrowingContinuation { continuation in
+        VZMacOSRestoreImage.load(from: ipswURL) { result in
          continuation.resume(with: result)
        }
      }
+
+      guard let requirements = image.mostFeaturefulSupportedConfiguration else {
+        throw UnsupportedRestoreImageError()
+      }
+
+      // Create NVRAM
+      _ = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)
+
+      // Create disk
+      try vmDir.resizeDisk(diskSizeGB)
+
+      name = vmDir.name
+      // Create config
+      config = VMConfig(
+        platform: Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: requirements.hardwareModel),
+        cpuCountMin: requirements.minimumSupportedCPUCount,
+        memorySizeMin: requirements.minimumSupportedMemorySize
+      )
+      // allocate at least 4 CPUs because otherwise VMs are frequently freezing
+      try config.setCPU(cpuCount: max(4, requirements.minimumSupportedCPUCount))
+      try config.save(toURL: vmDir.configURL)
+
+      // Initialize the virtual machine and its configuration
+      self.network = network
+      configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, nvramURL: vmDir.nvramURL,
+                                                  vmConfig: config, network: network,
+                                                  additionalStorageDevices: additionalStorageDevices,
+                                                  directorySharingDevices: directorySharingDevices,
+                                                  serialPorts: serialPorts
+      )
+      virtualMachine = VZVirtualMachine(configuration: configuration)
+
+      super.init()
+      virtualMachine.delegate = self
+
+      // Run automated installation
+      try await install(ipswURL)
    }
-  }
+
+    @MainActor
+    private func install(_ url: URL) async throws {
+      let installer = VZMacOSInstaller(virtualMachine: self.virtualMachine, restoringFromImageAt: url)
+      defaultLogger.appendNewLine("Installing OS...")
+      ProgressObserver(installer.progress).log(defaultLogger)
+
+      try await withTaskCancellationHandler(operation: {
+        try await withCheckedThrowingContinuation { continuation in
+          installer.install { result in
+            continuation.resume(with: result)
+          }
+        }
+      }, onCancel: {
+        installer.progress.cancel()
+      })
+    }
+  #endif

  @available(macOS 13, *)
  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16) async throws -> VM {
@@ -239,17 +248,32 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    }
  }

+  @MainActor
+  func connect(toPort: UInt32) async throws -> VZVirtioSocketConnection {
+    guard let socketDevice = virtualMachine.socketDevices.first else {
+      throw RuntimeError.VMSocketFailed(toPort, ", VM has no socket devices configured")
+    }
+
+    guard let virtioSocketDevice = socketDevice as? VZVirtioSocketDevice else {
+      throw RuntimeError.VMSocketFailed(toPort, ", expected VM's first socket device to have a type of VZVirtioSocketDevice, got \(type(of: socketDevice)) instead")
+    }
+
+    return try await virtioSocketDevice.connect(toPort: toPort)
+  }
+
  func run() async throws {
-    await withTaskCancellationHandler(operation: {
-      // Wait for the VM to finish running
-      // or for the exit condition
-      sema.wait()
-    }, onCancel: {
-      sema.signal()
-    })
+    do {
+      try await sema.waitUnlessCancelled()
+    } catch is CancellationError {
+      // Triggered by "tart stop", Ctrl+C, or closing the
+      // VM window, so shut down the VM gracefully below.
+    }

    if Task.isCancelled {
-      try await stop()
+      if (self.virtualMachine.state == VZVirtualMachine.State.running) {
+        print("Stopping VM...")
+        try await stop()
+      }
    }

    try await network.stop()
@@ -257,9 +281,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {

  @MainActor
  private func start(_ recovery: Bool) async throws {
-    let startOptions = VZMacOSVirtualMachineStartOptions()
-    startOptions.startUpFromMacOSRecovery = recovery
-    try await virtualMachine.start(options: startOptions)
+    #if arch(arm64)
+      let startOptions = VZMacOSVirtualMachineStartOptions()
+      startOptions.startUpFromMacOSRecovery = recovery
+      try await virtualMachine.start(options: startOptions)
+    #else
+      try await virtualMachine.start()
+    #endif
  }

  @MainActor
@@ -280,7 +308,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    additionalStorageDevices: [VZStorageDeviceConfiguration],
    directorySharingDevices: [VZDirectorySharingDeviceConfiguration],
    serialPorts: [VZSerialPortConfiguration],
-    suspendable: Bool = false
+    suspendable: Bool = false,
+    nested: Bool = false,
+    audio: Bool = true,
+    clipboard: Bool = true,
+    sync: VZDiskImageSynchronizationMode = .full,
+    caching: VZDiskImageCachingMode? = nil,
+    noTrackpad: Bool = false
  ) throws -> VZVirtualMachineConfiguration {
    let configuration = VZVirtualMachineConfiguration()

@@ -292,29 +326,40 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    configuration.memorySize = vmConfig.memorySize

    // Platform
-    configuration.platform = try vmConfig.platform.platform(nvramURL: nvramURL)
+    configuration.platform = try vmConfig.platform.platform(nvramURL: nvramURL, needsNestedVirtualization: nested)

    // Display
    configuration.graphicsDevices = [vmConfig.platform.graphicsDevice(vmConfig: vmConfig)]

    // Audio
-    if !suspendable {
-      let soundDeviceConfiguration = VZVirtioSoundDeviceConfiguration()
+    let soundDeviceConfiguration = VZVirtioSoundDeviceConfiguration()
+
+    if audio && !suspendable {
      let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
-      inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
      let outputAudioStreamConfiguration = VZVirtioSoundDeviceOutputStreamConfiguration()
+
+      inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
      outputAudioStreamConfiguration.sink = VZHostAudioOutputStreamSink()
+
      soundDeviceConfiguration.streams = [inputAudioStreamConfiguration, outputAudioStreamConfiguration]
-      configuration.audioDevices = [soundDeviceConfiguration]
+    } else {
+      // just a null speaker
+      soundDeviceConfiguration.streams = [VZVirtioSoundDeviceOutputStreamConfiguration()]
    }

+    configuration.audioDevices = [soundDeviceConfiguration]
+
    // Keyboard and mouse
    if suspendable, let platformSuspendable = vmConfig.platform.self as? PlatformSuspendable {
      configuration.keyboards = platformSuspendable.keyboardsSuspendable()
      configuration.pointingDevices = platformSuspendable.pointingDevicesSuspendable()
    } else {
      configuration.keyboards = vmConfig.platform.keyboards()
-      configuration.pointingDevices = vmConfig.platform.pointingDevices()
+      if noTrackpad {
+        configuration.pointingDevices = vmConfig.platform.pointingDevicesSimplified()
+      } else {
+        configuration.pointingDevices = vmConfig.platform.pointingDevices()
+      }
    }

    // Networking
@@ -325,19 +370,30 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
      return vio
    }

-    // Storage
-    let attachment: VZDiskImageStorageDeviceAttachment = vmConfig.os == .linux ?
-      // Use "cached" caching mode for virtio drive to prevent fs corruption on linux
-      try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false, cachingMode: .cached, synchronizationMode: .full) :
-      try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)
-
-    var device: VZStorageDeviceConfiguration
-    if #available(macOS 14, *), vmConfig.os == .linux {
-      device = VZNVMExpressControllerDeviceConfiguration(attachment: attachment)
-    } else {
-      device = VZVirtioBlockDeviceConfiguration(attachment: attachment)
+    // Clipboard sharing via Spice agent
+    if clipboard {
+      let spiceAgentConsoleDevice = VZVirtioConsoleDeviceConfiguration()
+      let spiceAgentPort = VZVirtioConsolePortConfiguration()
+      spiceAgentPort.name = VZSpiceAgentPortAttachment.spiceAgentPortName
+      let spiceAgentPortAttachment = VZSpiceAgentPortAttachment()
+      spiceAgentPortAttachment.sharesClipboard = true
+      spiceAgentPort.attachment = spiceAgentPortAttachment
+      spiceAgentConsoleDevice.ports[0] = spiceAgentPort
+      configuration.consoleDevices.append(spiceAgentConsoleDevice)
    }
-    var devices: [VZStorageDeviceConfiguration] = [device]
+
+    // Storage
+    var attachment = try VZDiskImageStorageDeviceAttachment(
+      url: diskURL,
+      readOnly: false,
+      // When not specified, use "cached" caching mode for Linux VMs to prevent file-system corruption[1]
+      //
+      // [1]: https://github.com/cirruslabs/tart/pull/675
+      cachingMode: caching ?? (vmConfig.os == .linux ? .cached : .automatic),
+      synchronizationMode: sync
+    )
+
+    var devices: [VZStorageDeviceConfiguration] = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]
    devices.append(contentsOf: additionalStorageDevices)
    configuration.storageDevices = devices

@@ -366,6 +422,9 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
      configuration.consoleDevices.append(consoleDevice)
    }

+    // Socket device
+    configuration.socketDevices = [VZVirtioSocketDeviceConfiguration()]
+
    try configuration.validate()

    return configuration
@@ -24,6 +24,7 @@ enum CodingKeys: String, CodingKey {
  case memorySize
  case macAddress
  case display
+  case displayRefit

  // macOS-specific keys
  case ecid
@@ -52,6 +53,7 @@ struct VMConfig: Codable {
  private(set) var memorySize: UInt64
  var macAddress: VZMACAddress
  var display: VMDisplayConfig = VMDisplayConfig()
+  var displayRefit: Bool?

  init(
    platform: Platform,
@@ -95,7 +97,14 @@ struct VMConfig: Codable {
    arch = try container.decodeIfPresent(Architecture.self, forKey: .arch) ?? .arm64
    switch os {
    case .darwin:
-      platform = try Darwin(from: decoder)
+      #if arch(arm64)
+        platform = try Darwin(from: decoder)
+      #else
+        throw DecodingError.dataCorruptedError(
+          forKey: .os,
+          in: container,
+          debugDescription: "Darwin VMs are only supported on Apple Silicon hosts")
+      #endif
    case .linux:
      platform = try Linux(from: decoder)
    }
@@ -114,6 +123,7 @@ struct VMConfig: Codable {
    self.macAddress = macAddress

    display = try container.decodeIfPresent(VMDisplayConfig.self, forKey: .display) ?? VMDisplayConfig()
+    displayRefit = try container.decodeIfPresent(Bool.self, forKey: .displayRefit)
  }

  func encode(to encoder: Encoder) throws {
@@ -129,23 +139,36 @@ struct VMConfig: Codable {
    try container.encode(memorySize, forKey: .memorySize)
    try container.encode(macAddress.string, forKey: .macAddress)
    try container.encode(display, forKey: .display)
+    if let displayRefit = displayRefit {
+      try container.encode(displayRefit, forKey: .displayRefit)
+    }
  }

  mutating func setCPU(cpuCount: Int) throws {
-    if cpuCount < cpuCountMin {
+    if os == .darwin && cpuCount < cpuCountMin {
      throw LessThanMinimalResourcesError("VM should have \(cpuCountMin) CPU cores"
        + " at minimum (requested \(cpuCount))")
    }

+    if cpuCount < VZVirtualMachineConfiguration.minimumAllowedCPUCount {
+      throw LessThanMinimalResourcesError("VM should have \(VZVirtualMachineConfiguration.minimumAllowedCPUCount) CPU cores"
+        + " at minimum (requested \(cpuCount))")
+    }
+
    self.cpuCount = cpuCount
  }

  mutating func setMemory(memorySize: UInt64) throws {
-    if memorySize < memorySizeMin {
+    if os == .darwin && memorySize < memorySizeMin {
      throw LessThanMinimalResourcesError("VM should have \(memorySizeMin) bytes"
        + " of memory at minimum (requested \(memorySize))")
    }

+    if memorySize < VZVirtualMachineConfiguration.minimumAllowedMemorySize {
+      throw LessThanMinimalResourcesError("VM should have \(VZVirtualMachineConfiguration.minimumAllowedMemorySize) bytes"
+        + " of memory at minimum (requested \(memorySize))")
+    }
+
    self.memorySize = memorySize
  }
 }
@@ -1,3 +1,4 @@
+import Compression
 import Foundation
 import Sentry

@@ -10,18 +11,7 @@ enum OCIError: Error {
 }

 extension VMDirectory {
-  private static let bufferSizeBytes = 64 * 1024 * 1024
-  private static let layerLimitBytes = 500 * 1000 * 1000
-
-  func pullFromRegistry(registry: Registry, reference: String, concurrency: UInt) async throws {
-    defaultLogger.appendNewLine("pulling manifest...")
-
-    let (manifest, _) = try await registry.pullManifest(reference: reference)
-
-    return try await pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency)
-  }
-
-  func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt) async throws {
+  func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt, localLayerCache: LocalLayerCache?, deduplicate: Bool) async throws {
    // Pull VM's config file layer and re-serialize it into a config file
    let configLayers = manifest.layers.filter {
      $0.mediaType == configMediaType
@@ -34,7 +24,7 @@ extension VMDirectory {
    }
    let configFile = try FileHandle(forWritingTo: configURL)
    try await registry.pullBlob(configLayers.first!.digest) { data in
-      configFile.write(data)
+      try configFile.write(contentsOf: data)
    }
    try configFile.close()

@@ -61,7 +51,19 @@ extension VMDirectory {
    let progress = Progress(totalUnitCount: diskCompressedSize)
    ProgressObserver(progress).log(defaultLogger)

-    try await diskImplType.pull(registry: registry, diskLayers: layers, diskURL: diskURL, concurrency: concurrency, progress: progress)
+    do {
+      try await diskImplType.pull(registry: registry, diskLayers: layers, diskURL: diskURL,
+                                  concurrency: concurrency, progress: progress,
+                                  localLayerCache: localLayerCache,
+                                  deduplicate: deduplicate)
+    } catch let error where error is FilterError {
+      throw RuntimeError.PullFailed("failed to decompress disk: \(error.localizedDescription)")
+    }
+
+    if deduplicate, let llc = localLayerCache {
+      // set custom attribute to remember deduplicated bytes
+      diskURL.setDeduplicatedBytes(llc.deduplicatedBytes)
+    }

    // Pull VM's NVRAM file layer and store it in an NVRAM file
    defaultLogger.appendNewLine("pulling NVRAM...")
@@ -77,12 +79,15 @@ extension VMDirectory {
    }
    let nvram = try FileHandle(forWritingTo: nvramURL)
    try await registry.pullBlob(nvramLayers.first!.digest) { data in
-      nvram.write(data)
+      try nvram.write(contentsOf: data)
    }
    try nvram.close()
+
+    // Serialize VM's manifest to enable better deduplication on subsequent "tart pull"'s
+    try manifest.toJSON().write(to: manifestURL)
  }

-  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int, diskFormat: String) async throws -> RemoteName {
+  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int, diskFormat: String, concurrency: UInt, labels: [String: String] = [:]) async throws -> RemoteName {
    var layers = Array<OCIManifestLayer>()

    // Read VM's config and push it as blob
@@ -101,9 +106,9 @@ extension VMDirectory {

    switch diskFormat {
    case "v1":
-      layers.append(contentsOf: try await DiskV1.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, progress: progress))
+      layers.append(contentsOf: try await DiskV1.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, concurrency: concurrency, progress: progress))
    case "v2":
-      layers.append(contentsOf: try await DiskV2.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, progress: progress))
+      layers.append(contentsOf: try await DiskV2.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, concurrency: concurrency, progress: progress))
    default:
      throw RuntimeError.OCIUnsupportedDiskFormat(diskFormat)
    }
@@ -116,7 +121,8 @@ extension VMDirectory {
    layers.append(OCIManifestLayer(mediaType: nvramMediaType, size: nvram.count, digest: nvramDigest))

    // Craft a stub OCI config for Docker Hub compatibility
-    let ociConfigJSON = try OCIConfig(architecture: config.arch, os: config.os).toJSON()
+    let ociConfigContainer = OCIConfig.ConfigContainer(Labels: labels)
+    let ociConfigJSON = try OCIConfig(architecture: config.arch, os: config.os, config: ociConfigContainer).toJSON()
    let ociConfigDigest = try await registry.pushBlob(fromData: ociConfigJSON, chunkSizeMb: chunkSizeMb)
    let manifest = OCIManifest(
      config: OCIManifestConfig(size: ociConfigJSON.count, digest: ociConfigDigest),
@@ -3,6 +3,12 @@ import Virtualization
 import CryptoKit

 struct VMDirectory: Prunable {
+  enum State: String {
+    case Running = "running"
+    case Suspended = "suspended"
+    case Stopped = "stopped"
+  }
+
  var baseURL: URL

  var configURL: URL {
@@ -17,6 +23,12 @@ struct VMDirectory: Prunable {
  var stateURL: URL {
    baseURL.appendingPathComponent("state.vzvmsave")
  }
+  var manifestURL: URL {
+    baseURL.appendingPathComponent("manifest.json")
+  }
+  var controlSocketURL: URL {
+    baseURL.appendingPathComponent("control.sock")
+  }

  var explicitlyPulledMark: URL {
    baseURL.appendingPathComponent(".explicitly-pulled")
@@ -47,13 +59,13 @@ struct VMDirectory: Prunable {
    return try lock.pid() != 0
  }

-  func state() throws -> String {
+  func state() throws -> State {
    if try running() {
-      return "running"
+      return State.Running
    } else if FileManager.default.fileExists(atPath: stateURL.path) {
-      return "suspended"
+      return State.Suspended
    } else {
-      return "stopped"
+      return State.Stopped
    }
  }

@@ -134,9 +146,18 @@ struct VMDirectory: Prunable {
    if !FileManager.default.fileExists(atPath: diskURL.path) {
      FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
    }
+
    let diskFileHandle = try FileHandle.init(forWritingTo: diskURL)
-    // macOS considers kilo being 1000 and not 1024
-    try diskFileHandle.truncate(atOffset: UInt64(sizeGB) * 1000 * 1000 * 1000)
+    let currentDiskFileLength = try diskFileHandle.seekToEnd()
+    let desiredDiskFileLength = UInt64(sizeGB) * 1000 * 1000 * 1000
+    if desiredDiskFileLength < currentDiskFileLength {
+      let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentDiskFileLength))
+      let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredDiskFileLength))
+      throw RuntimeError.InvalidDiskSize("new disk size of \(desiredLengthHuman) should be larger " +
+        "than the current disk size of \(currentLengthHuman)")
+    } else if desiredDiskFileLength > currentDiskFileLength {
+      try diskFileHandle.truncate(atOffset: desiredDiskFileLength)
+    }
    try diskFileHandle.close()
  }

@@ -156,6 +177,22 @@ struct VMDirectory: Prunable {
    try baseURL.accessDate()
  }

+  func allocatedSizeBytes() throws -> Int {
+    try configURL.allocatedSizeBytes() + diskURL.allocatedSizeBytes() + nvramURL.allocatedSizeBytes()
+  }
+
+  func allocatedSizeGB() throws -> Int {
+    try allocatedSizeBytes() / 1000 / 1000 / 1000
+  }
+
+  func deduplicatedSizeBytes() throws -> Int {
+    try configURL.deduplicatedSizeBytes() + diskURL.deduplicatedSizeBytes() + nvramURL.deduplicatedSizeBytes()
+  }
+
+  func deduplicatedSizeGB() throws -> Int {
+    try deduplicatedSizeBytes() / 1000 / 1000 / 1000
+  }
+
  func sizeBytes() throws -> Int {
    try configURL.sizeBytes() + diskURL.sizeBytes() + nvramURL.sizeBytes()
  }
@@ -24,6 +24,8 @@ class VMStorageHelper {
  private static func missingVMWrap<R: Any>(_ name: String, closure: () throws -> R) throws -> R {
    do {
      return try closure()
+    } catch RuntimeError.PIDLockMissing {
+      throw RuntimeError.VMDoesNotExist(name: name)
    } catch {
      if error.isFileNotFound() {
        throw RuntimeError.VMDoesNotExist(name: name)
@@ -47,6 +49,7 @@ extension Error {
 }

 enum RuntimeError : Error {
+  case Generic(_ message: String)
  case VMConfigurationError(_ message: String)
  case VMDoesNotExist(name: String)
  case VMMissingFiles(_ message: String)
@@ -55,10 +58,14 @@ enum RuntimeError : Error {
  case VMAlreadyRunning(_ message: String)
  case NoIPAddressFound(_ message: String)
  case DiskAlreadyInUse(_ message: String)
+  case FailedToOpenBlockDevice(_ path: String, _ explanation: String)
+  case InvalidDiskSize(_ message: String)
  case FailedToUpdateAccessDate(_ message: String)
  case PIDLockFailed(_ message: String)
+  case PIDLockMissing(_ message: String)
  case FailedToParseRemoteName(_ message: String)
  case VMTerminationFailed(_ message: String)
+  case ImproperlyFormattedHost(_ host: String, _ hint: String)
  case InvalidCredentials(_ message: String)
  case VMDirectoryAlreadyInitialized(_ message: String)
  case ExportFailed(_ message: String)
@@ -67,6 +74,10 @@ enum RuntimeError : Error {
  case OCIStorageError(_ message: String)
  case OCIUnsupportedDiskFormat(_ format: String)
  case SuspendFailed(_ message: String)
+  case PullFailed(_ message: String)
+  case VirtualMachineLimitExceeded(_ hint: String)
+  case VMSocketFailed(_ port: UInt32, _ explanation: String)
+  case TerminalOperationFailed(_ message: String)
 }

 protocol HasExitCode {
@@ -76,6 +87,8 @@ protocol HasExitCode {
 extension RuntimeError : CustomStringConvertible {
  public var description: String {
    switch self {
+    case .Generic(let message):
+      return message
    case .VMConfigurationError(let message):
      return message
    case .VMDoesNotExist(let name):
@@ -92,14 +105,22 @@ extension RuntimeError : CustomStringConvertible {
      return message
    case .DiskAlreadyInUse(let message):
      return message
+    case .FailedToOpenBlockDevice(let path, let explanation):
+      return "failed to open block device \(path): \(explanation)"
+    case .InvalidDiskSize(let message):
+      return message
    case .FailedToUpdateAccessDate(let message):
      return message
    case .PIDLockFailed(let message):
      return message
+    case .PIDLockMissing(let message):
+      return message
    case .FailedToParseRemoteName(let cause):
      return "failed to parse remote name: \(cause)"
    case .VMTerminationFailed(let message):
      return message
+    case .ImproperlyFormattedHost(let host, let hint):
+      return "improperly formatted host \"\(host)\" was provided\(hint)"
    case .InvalidCredentials(let message):
      return message
    case .VMDirectoryAlreadyInitialized(let message):
@@ -116,6 +137,14 @@ extension RuntimeError : CustomStringConvertible {
      return "OCI disk format \(format) is not supported by this version of Tart"
    case .SuspendFailed(let message):
      return "Failed to suspend the VM: \(message)"
+    case .PullFailed(let message):
+      return message
+    case .VirtualMachineLimitExceeded(let hint):
+      return "The number of VMs exceeds the system limit\(hint)"
+    case .VMSocketFailed(let port, let explanation):
+      return "Failed to establish a VM socket connection to port \(port): \(explanation)"
+    case .TerminalOperationFailed(let message):
+      return message
    }
  }
 }
@@ -66,7 +66,7 @@ class VMStorageLocal: PrunableStorage {
  }

  func prunables() throws -> [Prunable] {
-    try list().map { (_, vmDir) in vmDir }
+    try list().map { (_, vmDir) in vmDir }.filter { try !$0.running() }
  }

  func hasVMsWithMACAddress(macAddress: String) throws -> Bool {
@@ -1,5 +1,6 @@
 import Foundation
 import Sentry
+import Retry

 class VMStorageOCI: PrunableStorage {
  let baseURL = try! Config().tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
@@ -112,6 +113,10 @@ class VMStorageOCI: PrunableStorage {
        continue
      }

+      // Split the relative VM's path at the last component
+      // and figure out which character should be used
+      // to join them together, either ":" for tags or
+      // "@" for hashes
      let parts = [foundURL.deletingLastPathComponent().relativePath, foundURL.lastPathComponent]
      var name: String

@@ -122,6 +127,9 @@ class VMStorageOCI: PrunableStorage {
        name = parts.joined(separator: "@")
      }

+      // Remove the percent-encoding, if any
+      name = percentDecode(name)
+
      result.append((name, vmDir, isSymlink))
    }

@@ -132,9 +140,9 @@ class VMStorageOCI: PrunableStorage {
    try list().filter { (_, _, isSymlink) in !isSymlink }.map { (_, vmDir, _) in vmDir }
  }

-  func pull(_ name: RemoteName, registry: Registry, concurrency: UInt) async throws {
+  func pull(_ name: RemoteName, registry: Registry, concurrency: UInt, deduplicate: Bool) async throws {
    SentrySDK.configureScope { scope in
-      scope.setContext(value: ["imageName": name], key: "OCI")
+      scope.setContext(value: ["imageName": name.description], key: "OCI")
    }

    defaultLogger.appendNewLine("pulling manifest...")
@@ -188,7 +196,30 @@ class VMStorageOCI: PrunableStorage {
      }

      try await withTaskCancellationHandler(operation: {
-        try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency)
+        try await retry(maxAttempts: 5) {
+          // Choose the best base image which has the most deduplication ratio
+          let localLayerCache = try await chooseLocalLayerCache(name, manifest, registry)
+
+          if let llc = localLayerCache {
+            let deduplicatedHuman = ByteCountFormatter.string(fromByteCount: Int64(llc.deduplicatedBytes), countStyle: .file)
+
+            if deduplicate {
+              defaultLogger.appendNewLine("found an image \(llc.name) that will allow us to deduplicate \(deduplicatedHuman), using it as a base...")
+            } else {
+              defaultLogger.appendNewLine("found an image \(llc.name) that will allow us to avoid fetching \(deduplicatedHuman), will try use it...")
+            }
+          }
+
+          try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency, localLayerCache: localLayerCache, deduplicate: deduplicate)
+        } recoverFromFailure: { error in
+          if error is URLError {
+            print("Error pulling image: \"\(error.localizedDescription)\", attempting to re-try...")
+
+            return .retry
+          }
+
+          return .throw
+        }
        try move(digestName, from: tmpVMDir)
        transaction.finish()
      }, onCancel: {
@@ -207,6 +238,9 @@ class VMStorageOCI: PrunableStorage {
      // are excluded from garbage collection
      VMDirectory(baseURL: vmURL(name)).markExplicitlyPulled()
    }
+
+    // to explicitly set the image as being accessed so it won't get pruned immediately
+    _ = try VMStorageOCI().open(name)
  }

  func linked(from: RemoteName, to: RemoteName) -> Bool {
@@ -225,13 +259,66 @@ class VMStorageOCI: PrunableStorage {

    try gc()
  }
+
+  func chooseLocalLayerCache(_ name: RemoteName, _ manifest: OCIManifest, _ registry: Registry) async throws -> LocalLayerCache? {
+    // Establish a closure that will calculate how much bytes
+    // we'll deduplicate if we re-use the given manifest
+    let target = Swift.Set(manifest.layers)
+
+    let calculateDeduplicatedBytes = { (manifest: OCIManifest) -> UInt64 in
+      target.intersection(manifest.layers).map({ UInt64($0.size) }).reduce(0, +)
+    }
+
+    // Load OCI VM images and their manifests (if present)
+    var candidates: [(name: String, vmDir: VMDirectory, manifest: OCIManifest, deduplicatedBytes: UInt64)] = []
+
+    for (name, vmDir, isSymlink) in try list() {
+      if isSymlink {
+        continue
+      }
+
+      guard let manifestJSON = try? Data(contentsOf: vmDir.manifestURL) else {
+        continue
+      }
+
+      guard let manifest = try? OCIManifest(fromJSON: manifestJSON) else {
+        continue
+      }
+
+      candidates.append((name, vmDir, manifest, calculateDeduplicatedBytes(manifest)))
+    }
+
+    // Previously we haven't stored the OCI VM image manifests, but still fetched the VM image manifest if
+    // what the user was trying to pull was a tagged image, and we already had that image in the OCI VM cache
+    //
+    // Keep supporting this behavior for backwards comaptibility, but only communicate
+    // with the registry if we haven't already retrieved the manifest for that OCI VM image.
+    if name.reference.type == .Tag,
+       let vmDir = try? open(name),
+       let digest = try? digest(name),
+       try !candidates.contains(where: {try $0.manifest.digest() == digest}),
+       let (manifest, _) = try? await registry.pullManifest(reference: digest) {
+      candidates.append((name.description, vmDir, manifest, calculateDeduplicatedBytes(manifest)))
+    }
+
+    // Now, find the best match based on how many bytes we'll deduplicate
+    let choosen = candidates.filter {
+      $0.deduplicatedBytes > 1024 * 1024 * 1024 // save at least 1GB
+    }.max { left, right in
+      return left.deduplicatedBytes < right.deduplicatedBytes
+    }
+
+    return try choosen.flatMap({ choosen in
+      try LocalLayerCache(choosen.name, choosen.deduplicatedBytes, choosen.vmDir.diskURL, choosen.manifest)
+    })
+  }
 }

 extension URL {
  func appendingRemoteName(_ name: RemoteName) -> URL {
    var result: URL = self

-    for pathComponent in (name.host + "/" + name.namespace + "/" + name.reference.value).split(separator: "/") {
+    for pathComponent in (percentEncode(name.host) + "/" + name.namespace + "/" + name.reference.value).split(separator: "/") {
      result = result.appendingPathComponent(String(pathComponent))
    }

@@ -239,6 +326,23 @@ extension URL {
  }

  func appendingHost(_ name: RemoteName) -> URL {
-    self.appendingPathComponent(name.host, isDirectory: true)
+    self.appendingPathComponent(percentEncode(name.host), isDirectory: true)
  }
 }
+
+// Work around a pretty inane Swift's URL behavior where calling
+// appendingPathComponent() or deletingLastPathComponent() on a
+// URL like URL(filePath: "example.com:8080") (note the "filePath")
+// will flip its isFileURL from "true" to "false" and discard its
+// absolute path infromation (if any).
+//
+// The same kind of operations won't do anything to a URL like
+// URL(filePath: "127.0.0.1:8080"), which makes things even more
+// ridiculous.
+private func percentEncode(_ s: String) -> String {
+  return s.addingPercentEncoding(withAllowedCharacters: CharacterSet(charactersIn: ":").inverted)!
+}
+
+private func percentDecode(_ s: String) -> String {
+  s.removingPercentEncoding!
+}
@@ -15,7 +15,7 @@ class FullFledgedVNC: VNC {
    vnc.start()
  }

-  func waitForURL() async throws -> URL {
+  func waitForURL(netBridged: Bool) async throws -> URL {
    while true {
      // Port is 0 shortly after start(),
      // but will be initialized later
@@ -9,9 +9,9 @@ class ScreenSharingVNC: VNC {
    self.vmConfig = vmConfig
  }

-  func waitForURL() async throws -> URL {
+  func waitForURL(netBridged: Bool) async throws -> URL {
    let vmMACAddress = MACAddress(fromString: vmConfig.macAddress.string)!
-    let ip = try await IP.resolveIP(vmMACAddress, secondsToWait: 60)
+    let ip = try await IP.resolveIP(vmMACAddress, resolutionStrategy: netBridged ? .arp : .dhcp, secondsToWait: 60)

    if let ip = ip {
      return URL(string: "vnc://\(ip)")!
@@ -1,6 +1,6 @@
 import Foundation

 protocol VNC {
-  func waitForURL() async throws -> URL
+  func waitForURL(netBridged: Bool) async throws -> URL
  func stop() throws
 }
@@ -1,6 +1,8 @@
 import XCTest
@testable import tart

+import Virtualization
+
 final class DirectoryShareTests: XCTestCase {
  func testNamedParsing() throws {
    let share = try DirectoryShare(parseFrom: "build:/Users/admin/build")
@@ -8,25 +10,65 @@ final class DirectoryShareTests: XCTestCase {
    XCTAssertEqual(share.path, URL(filePath: "/Users/admin/build"))
    XCTAssertFalse(share.readOnly)
  }
-  
+
  func testNamedReadOnlyParsing() throws {
    let share = try DirectoryShare(parseFrom: "build:/Users/admin/build:ro")
    XCTAssertEqual(share.name, "build")
    XCTAssertEqual(share.path, URL(filePath: "/Users/admin/build"))
    XCTAssertTrue(share.readOnly)
  }
-  
+
  func testOptionalNameParsing() throws {
    let share = try DirectoryShare(parseFrom: "/Users/admin/build")
    XCTAssertNil(share.name)
    XCTAssertEqual(share.path, URL(filePath: "/Users/admin/build"))
    XCTAssertFalse(share.readOnly)
  }
-  
+
  func testOptionalNameReadOnlyParsing() throws {
    let share = try DirectoryShare(parseFrom: "/Users/admin/build:ro")
    XCTAssertNil(share.name)
    XCTAssertEqual(share.path, URL(filePath: "/Users/admin/build"))
    XCTAssertTrue(share.readOnly)
  }
+
+  func testMountTagParsing() throws {
+    let share = try DirectoryShare(parseFrom: "/Users/admin/build:tag=foo-bar")
+    XCTAssertNil(share.name)
+    XCTAssertEqual(share.path, URL(filePath: "/Users/admin/build"))
+    XCTAssertFalse(share.readOnly)
+    XCTAssertEqual(share.mountTag, "foo-bar")
+
+    let roShare = try DirectoryShare(parseFrom: "/Users/admin/build:ro,tag=foo-bar")
+    XCTAssertNil(roShare.name)
+    XCTAssertEqual(roShare.path, URL(filePath: "/Users/admin/build"))
+    XCTAssertTrue(roShare.readOnly)
+    XCTAssertEqual(roShare.mountTag, "foo-bar")
+
+    let inverseRoShare = try DirectoryShare(parseFrom: "/Users/admin/build:tag=foo-bar,ro")
+    XCTAssertNil(inverseRoShare.name)
+    XCTAssertEqual(inverseRoShare.path, URL(filePath: "/Users/admin/build"))
+    XCTAssertTrue(inverseRoShare.readOnly)
+    XCTAssertEqual(inverseRoShare.mountTag, "foo-bar")
+  }
+
+  func testURL() throws {
+    let archiveWithoutNameOrOptions = try DirectoryShare(parseFrom: "https://example.com/archive.tar.gz")
+    XCTAssertNil(archiveWithoutNameOrOptions.name)
+    XCTAssertEqual(archiveWithoutNameOrOptions.path, URL(string: "https://example.com/archive.tar.gz")!)
+    XCTAssertFalse(archiveWithoutNameOrOptions.readOnly)
+    XCTAssertEqual(archiveWithoutNameOrOptions.mountTag, VZVirtioFileSystemDeviceConfiguration.macOSGuestAutomountTag)
+
+    let archiveWithOptions = try DirectoryShare(parseFrom: "https://example.com/archive.tar.gz:ro,tag=sometag")
+    XCTAssertNil(archiveWithOptions.name)
+    XCTAssertEqual(archiveWithOptions.path, URL(string: "https://example.com/archive.tar.gz")!)
+    XCTAssertTrue(archiveWithOptions.readOnly)
+    XCTAssertEqual(archiveWithOptions.mountTag, "sometag")
+
+    let archiveWithNameAndOptions = try DirectoryShare(parseFrom: "somename:https://example.com/archive.tar.gz:ro,tag=sometag")
+    XCTAssertEqual(archiveWithNameAndOptions.name, "somename")
+    XCTAssertEqual(archiveWithNameAndOptions.path, URL(string: "https://example.com/archive.tar.gz")!)
+    XCTAssertTrue(archiveWithNameAndOptions.readOnly)
+    XCTAssertEqual(archiveWithNameAndOptions.mountTag, "sometag")
+  }
 }
@@ -36,7 +36,7 @@ final class LayerizerTests: XCTestCase {
    let pulledDiskFileURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)

    print("pushing disk...")
-    let diskLayers = try await DiskV1.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, progress: Progress())
+    let diskLayers = try await DiskV1.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, concurrency: 4, progress: Progress())

    print("pulling disk...")
    try await DiskV1.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())
@@ -57,7 +57,7 @@ final class LayerizerTests: XCTestCase {
    let pulledDiskFileURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)

    print("pushing disk...")
-    let diskLayers = try await DiskV2.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, progress: Progress())
+    let diskLayers = try await DiskV2.push(diskURL: originalDiskFileURL, registry: registry, chunkSizeMb: 0, concurrency: 4, progress: Progress())

    print("pulling disk...")
    try await DiskV2.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())
@@ -35,4 +35,27 @@ final class LeasesTests: XCTestCase {

    XCTAssertEqual(IPv4Address("1.2.3.4"), leases.ResolveMACAddress(macAddress: macAddress))
  }
+
+  func testDuplicateYetNotExpiredLeases() throws {
+    let macAddress = MACAddress(fromString: "11:22:33:44:55:66")!
+
+    let leases = try Leases("""
+    {
+            name=debian
+            ip_address=192.168.64.1
+            hw_address=1,\(macAddress)
+            identifier=1,\(macAddress)
+            lease=\(Int((Date() + 10.minutes).timeIntervalSince1970).hex)
+    }
+    {
+            name=debian
+            ip_address=192.168.64.2
+            hw_address=1,\(macAddress)
+            identifier=1,\(macAddress)
+            lease=\(Int((Date() + 5.minutes).timeIntervalSince1970).hex)
+    }
+    """)
+
+    XCTAssertEqual(IPv4Address("192.168.64.1"), leases.ResolveMACAddress(macAddress: macAddress))
+  }
 }
@@ -3,24 +3,26 @@ import XCTest

 final class TokenResponseTests: XCTestCase {
  func testBasic() throws {
+    var expectedTokenExpiresAtRange = DateInterval()
    let tokenResponseRaw = Data("{\"token\":\"some token\"}".utf8)
    let tokenResponse = try TokenResponse.parse(fromData: tokenResponseRaw)

    XCTAssertEqual(tokenResponse.token, "some token")

-    let expectedTokenExpiresAtRange = Date()...Date().addingTimeInterval(60)
+    expectedTokenExpiresAtRange.end = Date().addingTimeInterval(60)
    XCTAssertTrue(expectedTokenExpiresAtRange.contains(tokenResponse.tokenExpiresAt))

    XCTAssertTrue(tokenResponse.isValid())
  }

  func testExpirationBasic() throws {
+    var expectedTokenExpiresAtRange = DateInterval()
    let tokenResponseRaw = Data("{\"token\":\"some token\",\"expires_in\":2}".utf8)
    let tokenResponse = try TokenResponse.parse(fromData: tokenResponseRaw)

    XCTAssertEqual(tokenResponse.expiresIn, 2)

-    let expectedTokenExpiresAtRange = Date()...Date().addingTimeInterval(2)
+    expectedTokenExpiresAtRange.end = Date().addingTimeInterval(2)
    XCTAssertTrue(expectedTokenExpiresAtRange.contains(tokenResponse.tokenExpiresAt))

    XCTAssertTrue(tokenResponse.isValid())
@@ -31,7 +31,7 @@ class RegistryRunner {

  init() async throws {
    // Start container
-    let container = try Self.dockerCmd("run", "-d", "--rm", "-p", "5000", "registry:2")
+    let container = try Self.dockerCmd("run", "-d", "--rm", "-p", "127.0.0.1:0:5000", "registry:2")
      .trimmingCharacters(in: CharacterSet.newlines)
    containerID = container

@@ -39,7 +39,7 @@ class RegistryRunner {
    let port = try Self.dockerCmd("inspect", containerID, "--format", "{{(index (index .NetworkSettings.Ports \"5000/tcp\") 0).HostPort}}")
      .trimmingCharacters(in: CharacterSet.newlines)

-    registry = try Registry(urlComponents: URLComponents(string: "http://127.0.0.1:\(port)/v2/")!,
+    registry = try Registry(baseURL: URL(string: "http://127.0.0.1:\(port)/v2/")!,
                            namespace: "vm-image")

    // Wait for the Docker Registry to start
@@ -0,0 +1 @@
+root = true
@@ -0,0 +1,92 @@
+run:
+  timeout: 5m
+
+linters:
+  enable-all: true
+
+  disable:
+    # Messages like "struct of size 104 bytes could be of size 96 bytes" from a package
+    # that was last updated 2 years ago[1] are barely helpful.
+    #
+    # After all, we're writing the code for other people, so let's trust the compiler here (that's
+    # constantly evolving compared to this linter) and revisit this if memory usage becomes a problem.
+    #
+    # [1]: https://github.com/mdempsky/maligned/commit/6e39bd26a8c8b58c5a22129593044655a9e25959
+    - maligned
+
+    # We don't have high-performance requirements at this moment, so sacrificing
+    # the code readability for marginal performance gains is not worth it.
+    - prealloc
+
+    # New linters that require a lot of codebase churn and noise, but perhaps we can enable them in the future.
+    - nlreturn
+    - wrapcheck
+    - errorlint
+
+    # Unfortunately, we use globals due to how spf13/cobra works.
+    - gochecknoglobals
+
+    # That's fine that some Proto objects don't have all fields initialized
+    - exhaustivestruct
+
+    # Style linters that are total nuts.
+    - wsl
+    - gofumpt
+    - goimports
+    - funlen
+
+    # This conflicts with the Protocol Buffers Version 3 design,
+    # which is largely based on default values for struct fields.
+    - exhaustivestruct
+
+    # Enough parallelism for now.
+    - paralleltest
+
+    # Ill-based assumptions about identifiers like fmt.Println without taking context into account.
+    - forbidigo
+
+    # Advantages of using t.Helper() are too small to waste developer's cognitive stamina on it.
+    - thelper
+
+    # Too restrictive defaults, plus there's already a gocyclo linter in place.
+    - cyclop
+
+    # Gives false positives for textbook examples[1][2]
+    # [1]: https://github.com/charithe/durationcheck/issues/7
+    # [2]: https://golang.org/pkg/time/ (see "To convert an integer number of units to a Duration, multiply:")
+    - durationcheck
+
+    # No way to disable the "exported" check for the whole project[1]
+    # [1]: https://github.com/mgechev/revive/issues/244#issuecomment-560512162
+    - revive
+
+    # Unfortunately too much false-positives, e.g. for a 0700 umask or number 10 when using strconv.FormatInt()
+    - gomnd
+
+    # Needs package whitelists
+    - depguard
+
+    # Generates absolutely useless errors, e.g.
+    # "string `.yml` has 3 occurrences, make it a constant"
+    - goconst
+
+    # It's OK to not sort imports
+    - gci
+
+    # It's OK to not initialize some struct fields
+    - exhaustruct
+
+    # This is not a library, so it's OK to use dynamic errors
+    - goerr113
+
+    # fmt.Sprintf() looks a bit nicer than string addition
+    - perfsprint
+
+    # We can control this ourselves
+    - varnamelen
+    - contextcheck
+
+issues:
+  # Don't hide multiple issues that belong to one class since GitHub annotations can handle them all nicely.
+  max-issues-per-linter: 0
+  max-same-issues: 0
@@ -0,0 +1,210 @@
+# Benchmark
+
+Tart comes with a Golang-based benchmarking utility that allows one to easily compare host and guest performance.
+
+Currently, only Flexible I/O tester workloads are supported. To run them, first make sure that [passwordless sudo](https://serverfault.com/questions/160581/how-to-setup-passwordless-sudo-on-linux) is configured.
+
+Then, [install Golang](https://go.dev/). The easiest way is through [Homebrew](https://brew.sh/):
+
+```shell
+brew install go
+```
+
+Finally, run the following command from this (`benchmark/`) directory:
+
+```shell
+go run cmd/main.go fio --image ghcr.io/cirruslabs/macos-sequoia-base:latest --prepare 'sudo purge && sync'
+```
+
+You can also enable the debugging output to diagnose issues:
+
+```shell
+go run cmd/main.go fio --debug
+```
+
+## Results
+
+### Mar 27, 2024
+
+Host:
+
+* Hardware: Mac mini (Apple M2 Pro, 8 performance and 4 efficiency cores, 32 GB RAM, `Mac14,12`)
+* OS: macOS Sonoma 14.4.1
+
+Guest:
+
+* Hardware: [Virtualization.Framework](https://developer.apple.com/documentation/virtualization)
+* OS: macOS Sonoma 14.4.1
+
+```
+Name                    	Executor	Bandwidth	I/O operations
+Random writing of 1MB   	local   	2.6 GB/s 	649.35 kIOPS  
+Random writing of 1MB   	Tart    	2.5 GB/s 	620.22 kIOPS  
+Random writing of 10MB  	local   	2.6 GB/s 	651.74 kIOPS  
+Random writing of 10MB  	Tart    	2.5 GB/s 	615.52 kIOPS  
+Random writing of 100MB 	local   	1.9 GB/s 	481.51 kIOPS  
+Random writing of 100MB 	Tart    	2.0 GB/s 	493.31 kIOPS  
+Random writing of 1000MB	local   	1.7 GB/s 	414.89 kIOPS  
+Random writing of 1000MB	Tart    	1.1 GB/s 	287.4 kIOPS  
+```
+
+### Dec 2, 2024
+
+Host:
+
+* Hardware: MacBook Pro (Apple M1 Pro, 8 performance and 2 efficiency cores, 32 GB RAM, `MacBookPro18,3`)
+* OS: macOS Sequoia 15.1.1
+
+Guest:
+
+* Hardware: [Virtualization.Framework](https://developer.apple.com/documentation/virtualization)
+* OS: macOS Sonoma 14.6
+
+```
+Name                                    	Executor                                          	B/W (read)	B/W (write)	I/O (read) 	I/O (write) 	Latency (read)          	Latency (write)         	Latency (sync)      
+Single 4KiB random write process        	local                                             	0 B/s     	19 MB/s    	0 IOPS     	4.81 kIOPS  	0s ± 0s                 	203.418µs ± 155.865µs   	0s ± 0s             
+Single 4KiB random write process        	Tart                                              	0 B/s     	18 MB/s    	0 IOPS     	4.54 kIOPS  	0s ± 0s                 	213.655µs ± 188.822µs   	0s ± 0s             
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	19 MB/s    	0 IOPS     	4.68 kIOPS  	0s ± 0s                 	208.413µs ± 183.45µs    	0s ± 0s             
+Single 4KiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	24 MB/s    	0 IOPS     	6.11 kIOPS  	0s ± 0s                 	158.07µs ± 2.294654ms   	0s ± 0s             
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	22 MB/s    	0 IOPS     	5.49 kIOPS  	0s ± 0s                 	173.414µs ± 310.213µs   	0s ± 0s             
+16 parallel 64KiB random write processes	local                                             	0 B/s     	18 GB/s    	0 IOPS     	273.76 kIOPS	0s ± 0s                 	323.423µs ± 604.999µs   	0s ± 0s             
+16 parallel 64KiB random write processes	Tart                                              	0 B/s     	16 GB/s    	0 IOPS     	273.48 kIOPS	0s ± 0s                 	335.086µs ± 7.591748ms  	0s ± 0s             
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none")               	0 B/s     	18 GB/s    	0 IOPS     	281.49 kIOPS	0s ± 0s                 	326.655µs ± 7.485473ms  	0s ± 0s             
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="caching=cached")          	0 B/s     	17 GB/s    	0 IOPS     	266.79 kIOPS	0s ± 0s                 	340µs ± 7.868384ms      	0s ± 0s             
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	16 GB/s    	0 IOPS     	251.02 kIOPS	0s ± 0s                 	355.077µs ± 8.354218ms  	0s ± 0s             
+Single 1MiB random write process        	local                                             	0 B/s     	1.3 GB/s   	0 IOPS     	1.31 kIOPS  	0s ± 0s                 	751.716µs ± 370.731µs   	0s ± 0s             
+Single 1MiB random write process        	Tart                                              	0 B/s     	1.1 GB/s   	0 IOPS     	1.1 kIOPS   	0s ± 0s                 	885.833µs ± 3.572539ms  	0s ± 0s             
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	1.1 GB/s   	0 IOPS     	1.08 kIOPS  	0s ± 0s                 	898.427µs ± 3.464261ms  	0s ± 0s             
+Single 1MiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	1000 MB/s  	0 IOPS     	976.47 IOPS 	0s ± 0s                 	972.491µs ± 6.87654ms   	0s ± 0s             
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	1.1 GB/s   	0 IOPS     	1.03 kIOPS  	0s ± 0s                 	925.545µs ± 4.261693ms  	0s ± 0s             
+Random reads/writes (4k)                	local                                             	62 MB/s   	62 MB/s    	15.37 kIOPS	15.37 kIOPS 	2.059453ms ± 1.431822ms 	2.098761ms ± 1.445082ms 	0s ± 0s             
+Random reads/writes (4k)                	Tart                                              	38 MB/s   	38 MB/s    	9.6 kIOPS  	9.61 kIOPS  	3.30369ms ± 1.500464ms  	3.350589ms ± 1.512986ms 	0s ± 0s             
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none")               	39 MB/s   	39 MB/s    	9.82 kIOPS 	9.83 kIOPS  	3.228106ms ± 1.367512ms 	3.27626ms ± 1.385964ms  	0s ± 0s             
+Random reads/writes (4k)                	Tart (--root-disk-opts="caching=cached")          	35 MB/s   	35 MB/s    	8.74 kIOPS 	8.76 kIOPS  	3.640772ms ± 15.472355ms	3.661779ms ± 15.264288ms	0s ± 0s             
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none,caching=cached")	24 MB/s   	24 MB/s    	5.98 kIOPS 	5.99 kIOPS  	5.31188ms ± 4.55205ms   	5.375047ms ± 5.113847ms 	0s ± 0s             
+Random reads/writes (64k)               	local                                             	435 MB/s  	436 MB/s   	6.79 kIOPS 	6.8 kIOPS   	4.955892ms ± 2.066685ms 	4.440414ms ± 1.860036ms 	0s ± 0s             
+Random reads/writes (64k)               	Tart                                              	352 MB/s  	353 MB/s   	5.5 kIOPS  	5.51 kIOPS  	5.946067ms ± 2.041124ms 	5.658948ms ± 1.928372ms 	0s ± 0s             
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none")               	331 MB/s  	332 MB/s   	5.16 kIOPS 	5.17 kIOPS  	6.330765ms ± 1.726782ms 	6.033862ms ± 1.671028ms 	0s ± 0s             
+Random reads/writes (64k)               	Tart (--root-disk-opts="caching=cached")          	428 MB/s  	428 MB/s   	6.68 kIOPS 	6.69 kIOPS  	4.661666ms ± 18.342779ms	4.904961ms ± 18.396772ms	0s ± 0s             
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none,caching=cached")	297 MB/s  	298 MB/s   	4.64 kIOPS 	4.65 kIOPS  	6.591009ms ± 2.827053ms 	7.166883ms ± 3.001036ms 	0s ± 0s             
+sync test                               	local                                             	0 B/s     	48 MB/s    	0 IOPS     	21.15 kIOPS 	0s ± 0s                 	23.471µs ± 81.868µs     	23.374µs ± 6.255µs  
+sync test                               	Tart                                              	0 B/s     	24 MB/s    	0 IOPS     	10.72 kIOPS 	0s ± 0s                 	24.983µs ± 61.761µs     	67.575µs ± 76.196µs 
+sync test                               	Tart (--root-disk-opts="sync=none")               	0 B/s     	21 MB/s    	0 IOPS     	9.5 kIOPS   	0s ± 0s                 	26.973µs ± 63.935µs     	77.388µs ± 47.103µs 
+sync test                               	Tart (--root-disk-opts="caching=cached")          	0 B/s     	30 MB/s    	0 IOPS     	13.19 kIOPS 	0s ± 0s                 	11.923µs ± 25.225µs     	62.894µs ± 208.933µs
+sync test                               	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	38 MB/s    	0 IOPS     	17.02 kIOPS 	0s ± 0s                 	10.124µs ± 21.868µs     	47.803µs ± 33.706µs
+```
+
+### Dec 4, 2024
+
+Host:
+
+* AWS instance: `mac2.metal` + `gp3` EBS volume
+* Hardware: Mac mini (Apple M1, 4 performance and 4 efficiency cores, 16 GB RAM, `Macmini9,1`)
+* OS: macOS Sequoia 15.0
+
+Guest:
+
+* Hardware: [Virtualization.Framework](https://developer.apple.com/documentation/virtualization)
+* OS: macOS Sonoma 14.6
+
+```
+Name                                    	Executor                                          	B/W (read)	B/W (write)	I/O (read) 	I/O (write) 	Latency (read)            	Latency (write)           	Latency (sync)         
+Single 4KiB random write process        	local                                             	0 B/s     	4.4 MB/s   	0 IOPS     	1.1 kIOPS   	0s ± 0s                   	702.357µs ± 359.925µs     	0s ± 0s                
+Single 4KiB random write process        	Tart                                              	0 B/s     	2.6 MB/s   	0 IOPS     	656.37 IOPS 	0s ± 0s                   	1.140086ms ± 1.450472ms   	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	2.7 MB/s   	0 IOPS     	677.07 IOPS 	0s ± 0s                   	1.179872ms ± 1.219626ms   	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	3.3 MB/s   	0 IOPS     	832.66 IOPS 	0s ± 0s                   	948.648µs ± 94.141338ms   	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	15 MB/s    	0 IOPS     	3.65 kIOPS  	0s ± 0s                   	260.717µs ± 19.977757ms   	0s ± 0s                
+16 parallel 64KiB random write processes	local                                             	0 B/s     	9.5 GB/s   	0 IOPS     	147.89 kIOPS	0s ± 0s                   	753.289µs ± 8.028974ms    	0s ± 0s                
+16 parallel 64KiB random write processes	Tart                                              	0 B/s     	10 GB/s    	0 IOPS     	176.96 kIOPS	0s ± 0s                   	429.83µs ± 33.792264ms    	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none")               	0 B/s     	12 GB/s    	0 IOPS     	180.89 kIOPS	0s ± 0s                   	383.524µs ± 17.524971ms   	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="caching=cached")          	0 B/s     	336 MB/s   	0 IOPS     	5.24 kIOPS  	0s ± 0s                   	9.970844ms ± 365.808663ms 	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	9.4 GB/s   	0 IOPS     	147.04 kIOPS	0s ± 0s                   	524.139µs ± 34.100009ms   	0s ± 0s                
+Single 1MiB random write process        	local                                             	0 B/s     	178 MB/s   	0 IOPS     	173.36 IOPS 	0s ± 0s                   	3.835103ms ± 2.917977ms   	0s ± 0s                
+Single 1MiB random write process        	Tart                                              	0 B/s     	140 MB/s   	0 IOPS     	136.48 IOPS 	0s ± 0s                   	4.721178ms ± 7.744965ms   	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	144 MB/s   	0 IOPS     	140.63 IOPS 	0s ± 0s                   	4.443507ms ± 11.572454ms  	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	47 MB/s    	0 IOPS     	45.55 IOPS  	0s ± 0s                   	13.267881ms ± 358.283094ms	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	196 MB/s   	0 IOPS     	191.4 IOPS  	0s ± 0s                   	4.102516ms ± 73.117503ms  	0s ± 0s                
+Random reads/writes (4k)                	local                                             	8.7 MB/s  	8.7 MB/s   	2.16 kIOPS 	2.16 kIOPS  	193.370794ms ± 42.593607ms	222.272016ms ± 56.586971ms	0s ± 0s                
+Random reads/writes (4k)                	Tart                                              	4.1 MB/s  	4.1 MB/s   	1.02 kIOPS 	1.03 kIOPS  	31.038867ms ± 13.508668ms 	31.184305ms ± 14.032766ms 	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none")               	4.2 MB/s  	4.2 MB/s   	1.04 kIOPS 	1.05 kIOPS  	30.368422ms ± 13.505627ms 	30.595412ms ± 13.840944ms 	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="caching=cached")          	2.2 MB/s  	2.2 MB/s   	545.33 IOPS	548.86 IOPS 	59.31316ms ± 716.351086ms 	57.647852ms ± 711.503882ms	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none,caching=cached")	6.0 MB/s  	6.0 MB/s   	1.5 kIOPS  	1.5 kIOPS   	21.244222ms ± 47.808399ms 	21.39459ms ± 44.716307ms  	0s ± 0s                
+Random reads/writes (64k)               	local                                             	121 MB/s  	121 MB/s   	1.89 kIOPS 	1.89 kIOPS  	61.894699ms ± 21.353345ms 	73.176462ms ± 13.02948ms  	0s ± 0s                
+Random reads/writes (64k)               	Tart                                              	72 MB/s   	72 MB/s    	1.12 kIOPS 	1.12 kIOPS  	27.842263ms ± 15.320781ms 	29.161858ms ± 15.765314ms 	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none")               	71 MB/s   	72 MB/s    	1.11 kIOPS 	1.11 kIOPS  	28.009493ms ± 16.333136ms 	29.285868ms ± 16.540589ms 	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="caching=cached")          	28 MB/s   	28 MB/s    	441.85 IOPS	444.81 IOPS 	71.726725ms ± 633.215756ms	72.597238ms ± 630.969305ms	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none,caching=cached")	81 MB/s   	81 MB/s    	1.26 kIOPS 	1.26 kIOPS  	24.872043ms ± 36.980111ms 	25.568559ms ± 37.027145ms 	0s ± 0s                
+sync test                               	local                                             	0 B/s     	1.9 MB/s   	0 IOPS     	868.08 IOPS 	0s ± 0s                   	92.08µs ± 233.598µs       	1.059033ms ± 98.751µs  
+sync test                               	Tart                                              	0 B/s     	1.5 MB/s   	0 IOPS     	649.42 IOPS 	0s ± 0s                   	146.737µs ± 434.261µs     	1.391898ms ± 699.148µs 
+sync test                               	Tart (--root-disk-opts="sync=none")               	0 B/s     	1.3 MB/s   	0 IOPS     	568.82 IOPS 	0s ± 0s                   	158.736µs ± 504.002µs     	1.59798ms ± 14.161331ms
+sync test                               	Tart (--root-disk-opts="caching=cached")          	0 B/s     	13 MB/s    	0 IOPS     	5.77 kIOPS  	0s ± 0s                   	26.596µs ± 832.169µs      	145.785µs ± 2.864048ms 
+sync test                               	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	19 MB/s    	0 IOPS     	8.37 kIOPS  	0s ± 0s                   	20.135µs ± 108.817µs      	98.274µs ± 239.631µs   
+```
+
+Host:
+
+* AWS instance: `mac2.metal` + `gp3` EBS volume
+* Hardware: Mac mini (Apple M1, 4 performance and 4 efficiency cores, 16 GB RAM, `Macmini9,1`)
+* OS: macOS Sequoia 15.0
+
+Guest:
+
+* Hardware: [Virtualization.Framework](https://developer.apple.com/documentation/virtualization)
+* OS: macOS Sequoia 15.1
+
+```
+Name                                    	Executor                                          	B/W (read)	B/W (write)	I/O (read) 	I/O (write) 	Latency (read)            	Latency (write)           	Latency (sync)         
+Single 4KiB random write process        	local                                             	0 B/s     	4.8 MB/s   	0 IOPS     	1.19 kIOPS  	0s ± 0s                   	690.818µs ± 326.595µs     	0s ± 0s                
+Single 4KiB random write process        	Tart                                              	0 B/s     	2.8 MB/s   	0 IOPS     	700.94 IOPS 	0s ± 0s                   	1.090362ms ± 918.444µs    	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	3.0 MB/s   	0 IOPS     	746.23 IOPS 	0s ± 0s                   	1.028192ms ± 974.533µs    	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	4.2 MB/s   	0 IOPS     	1.04 kIOPS  	0s ± 0s                   	916.36µs ± 105.318323ms   	0s ± 0s                
+Single 4KiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	14 MB/s    	0 IOPS     	3.57 kIOPS  	0s ± 0s                   	269.796µs ± 22.419599ms   	0s ± 0s                
+16 parallel 64KiB random write processes	local                                             	0 B/s     	9.5 GB/s   	0 IOPS     	148.74 kIOPS	0s ± 0s                   	753.46µs ± 8.06509ms      	0s ± 0s                
+16 parallel 64KiB random write processes	Tart                                              	0 B/s     	5.2 GB/s   	0 IOPS     	81.46 kIOPS 	0s ± 0s                   	778.624µs ± 11.705178ms   	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none")               	0 B/s     	5.3 GB/s   	0 IOPS     	83.47 kIOPS 	0s ± 0s                   	865.448µs ± 38.369176ms   	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="caching=cached")          	0 B/s     	116 MB/s   	0 IOPS     	1.8 kIOPS   	0s ± 0s                   	37.601112ms ± 727.319309ms	0s ± 0s                
+16 parallel 64KiB random write processes	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	5.3 GB/s   	0 IOPS     	83.19 kIOPS 	0s ± 0s                   	900.751µs ± 51.223205ms   	0s ± 0s                
+Single 1MiB random write process        	local                                             	0 B/s     	177 MB/s   	0 IOPS     	173.27 IOPS 	0s ± 0s                   	3.833194ms ± 2.873871ms   	0s ± 0s                
+Single 1MiB random write process        	Tart                                              	0 B/s     	151 MB/s   	0 IOPS     	147.44 IOPS 	0s ± 0s                   	4.925853ms ± 7.793808ms   	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none")               	0 B/s     	151 MB/s   	0 IOPS     	147.87 IOPS 	0s ± 0s                   	4.884797ms ± 7.563512ms   	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="caching=cached")          	0 B/s     	72 MB/s    	0 IOPS     	69.9 IOPS   	0s ± 0s                   	8.909771ms ± 214.311644ms 	0s ± 0s                
+Single 1MiB random write process        	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	159 MB/s   	0 IOPS     	155.69 IOPS 	0s ± 0s                   	4.863448ms ± 88.965211ms  	0s ± 0s                
+Random reads/writes (4k)                	local                                             	8.7 MB/s  	8.7 MB/s   	2.16 kIOPS 	2.16 kIOPS  	193.353233ms ± 42.728494ms	222.325905ms ± 56.901372ms	0s ± 0s                
+Random reads/writes (4k)                	Tart                                              	3.5 MB/s  	3.5 MB/s   	862.89 IOPS	865.54 IOPS 	36.893229ms ± 12.644216ms 	37.143334ms ± 12.772017ms 	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none")               	3.6 MB/s  	3.6 MB/s   	907.4 IOPS 	911.55 IOPS 	35.048969ms ± 10.559354ms 	35.3046ms ± 10.67824ms    	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="caching=cached")          	2.7 MB/s  	2.8 MB/s   	684.11 IOPS	688.05 IOPS 	48.815322ms ± 687.806727ms	44.395556ms ± 635.532064ms	0s ± 0s                
+Random reads/writes (4k)                	Tart (--root-disk-opts="sync=none,caching=cached")	7.0 MB/s  	7.0 MB/s   	1.74 kIOPS 	1.74 kIOPS  	18.00448ms ± 93.784447ms  	18.617037ms ± 107.423001ms	0s ± 0s                
+Random reads/writes (64k)               	local                                             	121 MB/s  	121 MB/s   	1.89 kIOPS 	1.89 kIOPS  	61.983727ms ± 21.324782ms 	73.228597ms ± 12.730945ms 	0s ± 0s                
+Random reads/writes (64k)               	Tart                                              	75 MB/s   	75 MB/s    	1.17 kIOPS 	1.17 kIOPS  	26.830538ms ± 7.643051ms  	27.709602ms ± 7.830965ms  	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none")               	76 MB/s   	77 MB/s    	1.19 kIOPS 	1.19 kIOPS  	26.255337ms ± 7.302592ms  	27.256805ms ± 7.388266ms  	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="caching=cached")          	32 MB/s   	33 MB/s    	505.26 IOPS	508.66 IOPS 	65.170269ms ± 747.794957ms	61.062186ms ± 695.614904ms	0s ± 0s                
+Random reads/writes (64k)               	Tart (--root-disk-opts="sync=none,caching=cached")	79 MB/s   	79 MB/s    	1.23 kIOPS 	1.23 kIOPS  	25.861503ms ± 171.669777ms	25.992302ms ± 164.647788ms	0s ± 0s                
+sync test                               	local                                             	0 B/s     	1.9 MB/s   	0 IOPS     	865.16 IOPS 	0s ± 0s                   	100.95µs ± 268.722µs      	1.054051ms ± 365.377µs 
+sync test                               	Tart                                              	0 B/s     	1.6 MB/s   	0 IOPS     	704.13 IOPS 	0s ± 0s                   	133.886µs ± 390.263µs     	1.285085ms ± 575.27µs  
+sync test                               	Tart (--root-disk-opts="sync=none")               	0 B/s     	1.6 MB/s   	0 IOPS     	728.26 IOPS 	0s ± 0s                   	129.246µs ± 472.724µs     	1.242713ms ± 1.281286ms
+sync test                               	Tart (--root-disk-opts="caching=cached")          	0 B/s     	35 MB/s    	0 IOPS     	15.67 kIOPS 	0s ± 0s                   	11.319µs ± 24.771µs       	51.731µs ± 42.208µs    
+sync test                               	Tart (--root-disk-opts="sync=none,caching=cached")	0 B/s     	17 MB/s    	0 IOPS     	7.39 kIOPS  	0s ± 0s                   	21.23µs ± 81.749µs        	113.239µs ± 191.266µs  
+```
+
+### March 23, 2025
+
+Host:
+
+* Hardware: Mac mini (Apple M2 Pro, 8 performance and 4 efficiency cores, 32 GB RAM, `Mac14,12`)
+* OS: macOS Sequoia 15.3.2
+* Xcode: 16.2
+
+Guest:
+
+* Hardware: [Virtualization.Framework](https://developer.apple.com/documentation/virtualization)
+* OS: macOS Sonoma 15.3.2 
+* Xcode: 16.2
+
+```
+Name                    	Executor                                          	Time 
+XcodeBenchmark (d869315)	local                                             	2m19s
+XcodeBenchmark (d869315)	Tart                                              	3m59s
+XcodeBenchmark (d869315)	Tart (--root-disk-opts="sync=none")               	3m48s
+XcodeBenchmark (d869315)	Tart (--root-disk-opts="caching=cached")          	3m35s
+XcodeBenchmark (d869315)	Tart (--root-disk-opts="sync=none,caching=cached")	3m14s
+```
@@ -0,0 +1,23 @@
+package main
+
+import (
+	"context"
+	"github.com/cirruslabs/tart/benchmark/internal/command"
+	"log"
+	"os"
+	"os/signal"
+)
+
+func main() {
+	// Set up a signal-interruptible context
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
+
+	// Run the root command
+	if err := command.NewCommand().ExecuteContext(ctx); err != nil {
+		cancel()
+
+		log.Fatal(err)
+	}
+
+	cancel()
+}
@@ -0,0 +1,33 @@
+module github.com/cirruslabs/tart/benchmark
+
+go 1.22.1
+toolchain go1.24.1
+
+require (
+	github.com/avast/retry-go/v4 v4.5.1
+	github.com/dustin/go-humanize v1.0.1
+	github.com/google/uuid v1.6.0
+	github.com/gosuri/uitable v0.0.4
+	github.com/shirou/gopsutil v3.21.11+incompatible
+	github.com/spf13/cobra v1.8.0
+	github.com/stretchr/testify v1.9.0
+	go.uber.org/zap v1.27.0
+	golang.org/x/crypto v0.35.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/fatih/color v1.16.0 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-runewidth v0.0.15 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/sys v0.30.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
@@ -0,0 +1,59 @@
+github.com/avast/retry-go/v4 v4.5.1 h1:AxIx0HGi4VZ3I02jr78j5lZ3M6x1E0Ivxa6b0pUUh7o=
+github.com/avast/retry-go/v4 v4.5.1/go.mod h1:/sipNsvNB3RRuT5iNcb6h73nw3IBmXJ/H3XrCQYSOpc=
+github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/fatih/color v1.16.0 h1:zmkK9Ngbjj+K0yRhTVONQh1p/HknKYSlNT+vZCzyokM=
+github.com/fatih/color v1.16.0/go.mod h1:fL2Sau1YI5c0pdGEVCbKQbLXB6edEj1ZgiY4NijnWvE=
+github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gosuri/uitable v0.0.4 h1:IG2xLKRvErL3uhY6e1BylFzG+aJiwQviDDTfOKeKTpY=
+github.com/gosuri/uitable v0.0.4/go.mod h1:tKR86bXuXPZazfOTG1FIzvjIdXzd0mo4Vtn16vt0PJo=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U=
+github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/shirou/gopsutil v3.21.11+incompatible h1:+1+c1VGhc88SSonWP6foOcLhvnKlUeu/erjjvaPEYiI=
+github.com/shirou/gopsutil v3.21.11+incompatible/go.mod h1:5b4v6he4MtMOwMlS0TUMTu2PcXUg8+E1lC7eC3UO/RA=
+github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0=
+github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
+go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
+golang.org/x/crypto v0.35.0 h1:b15kiHdrGCHrP6LvwaQ3c03kgNhhiMgvlhxHQhmg2Xs=
+golang.org/x/crypto v0.35.0/go.mod h1:dy7dXNW32cAb/6/PRuTNsix8T+vJAqvuIy5Bli/x0YQ=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.29.0 h1:L6pJp37ocefwRRtYPKSWOWzOtWSxVajvz2ldH/xi3iU=
+golang.org/x/term v0.29.0/go.mod h1:6bl4lRlvVuDgSf3179VpIxBF0o10JUpXWOnI7nErv7s=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -0,0 +1,69 @@
+package fio
+
+type Benchmark struct {
+	Name    string
+	Command string
+}
+
+var benchmarks = []Benchmark{
+	{
+		// Ars Technica's "Single 4KiB random write process" test[1]
+		// with JSON output and created file cleanup
+		//
+		// [1]: https://arstechnica.com/gadgets/2020/02/how-fast-are-your-disks-find-out-the-open-source-way-with-fio/
+		Name: "Single 4KiB random write process",
+		Command: "fio --name=benchmark --ioengine=posixaio --rw=randwrite --bs=4k --size=4g --numjobs=1 --iodepth=1 --runtime=60 --time_based --end_fsync=1" +
+			" --output-format json --unlink 1",
+	},
+	{
+		// Ars Technica's "16 parallel 64KiB random write processes" test[1]
+		// with JSON outpu, created file cleanup and group reporting (for
+		// easier analysis)
+		//
+		// [1]: https://arstechnica.com/gadgets/2020/02/how-fast-are-your-disks-find-out-the-open-source-way-with-fio/
+		Name: "16 parallel 64KiB random write processes",
+		Command: "fio --name=benchmark --ioengine=posixaio --rw=randwrite --bs=64k --size=256m --numjobs=16 --iodepth=16 --runtime=60 --time_based --end_fsync=1" +
+			" --output-format json --unlink 1 --group_reporting",
+	},
+	{
+		// Ars Technica's "16 parallel 64KiB random write processes" test[1]
+		// with JSON output, created file cleanup and reduced file I/O size
+		// from 16 to 10 GB to avoid "No space left on device".
+		//
+		// [1]: https://arstechnica.com/gadgets/2020/02/how-fast-are-your-disks-find-out-the-open-source-way-with-fio/
+		Name: "Single 1MiB random write process",
+		Command: "fio --name=benchmark --ioengine=posixaio --rw=randwrite --bs=1m --size=10g --numjobs=1 --iodepth=1 --runtime=60 --time_based --end_fsync=1" +
+			" --output-format json --unlink 1",
+	},
+	{
+		// Oracle's "Test random read/writes" (in IOPS Performance Tests[1]) category
+		// with JSON output, created file cleanup, without ETA newline, without custom
+		// file path, with file I/O size reduced from 500GB to 2GB to prevent
+		// "No space left on device" and with posixaio instead of libaio.
+		//
+		// [1]: https://docs.oracle.com/en-us/iaas/Content/Block/References/samplefiocommandslinux.htm#FIO_Commands
+		Name: "Random reads/writes (4k)",
+		Command: "fio --name=benchmark --size=2GB --direct=1 --rw=randrw --bs=4k --ioengine=posixaio --iodepth=256 --runtime=120 --numjobs=4 --time_based --group_reporting" +
+			" --output-format json --unlink 1",
+	},
+	{
+		// Oracle's "Test random read/writes" (in Throughput Performance Tests[1]) category
+		// with JSON output, created file cleanup, without ETA newline, without custom
+		// file path, with file I/O size reduced from 500GB to 2GB to prevent
+		// "No space left on device" and with posixaio instead of libaio.
+		//
+		// [1]: https://docs.oracle.com/en-us/iaas/Content/Block/References/samplefiocommandslinux.htm#Throughput_Performance_Tests
+		Name: "Random reads/writes (64k)",
+		Command: "fio --name=benchmark --size=2GB --direct=1 --rw=randrw --bs=64k --ioengine=posixaio --iodepth=64 --runtime=120 --numjobs=4 --time_based --group_reporting" +
+			" --output-format json --unlink 1",
+	},
+	{
+		// RedHat's "How can I test to see if my environment is fast enough for etcd"[1]
+		// with custom name
+		//
+		// [1]: https://access.redhat.com/solutions/5726511
+		Name: "sync test",
+		Command: "mkdir -p test-data && fio --name=benchmark --rw=write --ioengine=sync --fdatasync=1 --directory=test-data --size=22m --bs=2300" +
+			" --output-format json --unlink 1",
+	},
+}
@@ -0,0 +1,138 @@
+package fio
+
+import (
+	"encoding/json"
+	"fmt"
+	executorpkg "github.com/cirruslabs/tart/benchmark/internal/executor"
+	"github.com/dustin/go-humanize"
+	"github.com/gosuri/uitable"
+	"github.com/spf13/cobra"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapio"
+	"os"
+	"os/exec"
+)
+
+var debug bool
+var image string
+var prepare string
+
+func NewCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "fio",
+		Short: "run Flexible I/O tester (fio) benchmarks",
+		RunE:  run,
+	}
+
+	cmd.Flags().BoolVar(&debug, "debug", false, "enable debug logging")
+	cmd.Flags().StringVar(&image, "image", "ghcr.io/cirruslabs/macos-sonoma-base:latest", "image to use for testing")
+	cmd.Flags().StringVar(&prepare, "prepare", "", "command to run before running each benchmark")
+
+	return cmd
+}
+
+func run(cmd *cobra.Command, args []string) error {
+	config := zap.NewProductionConfig()
+	if debug {
+		config.Level = zap.NewAtomicLevelAt(zap.DebugLevel)
+	}
+	logger, err := config.Build()
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = logger.Sync()
+	}()
+
+	table := uitable.New()
+	table.AddRow("Name", "Executor", "B/W (read)", "B/W (write)", "I/O (read)", "I/O (write)",
+		"Latency (read)", "Latency (write)", "Latency (sync)")
+
+	for _, benchmark := range benchmarks {
+		for _, executorInitializer := range executorpkg.DefaultInitializers(cmd.Context(), image, logger) {
+			if prepare != "" {
+				shell := "/bin/sh"
+
+				if shellFromEnv, ok := os.LookupEnv("SHELL"); ok {
+					shell = shellFromEnv
+				}
+
+				logger.Sugar().Infof("running prepare command %q using shell %q",
+					prepare, shell)
+
+				cmd := exec.CommandContext(cmd.Context(), shell, "-c", prepare)
+
+				loggerWriter := &zapio.Writer{Log: logger, Level: zap.DebugLevel}
+
+				cmd.Stdout = loggerWriter
+				cmd.Stderr = loggerWriter
+
+				if err := cmd.Run(); err != nil {
+					return fmt.Errorf("failed to run prepare command %q: %v", prepare, err)
+				}
+			}
+
+			logger.Sugar().Infof("initializing executor %s", executorInitializer.Name)
+
+			executor, err := executorInitializer.Fn()
+			if err != nil {
+				return err
+			}
+
+			logger.Sugar().Infof("installing Flexible I/O tester (fio) on executor %s",
+				executorInitializer.Name)
+
+			if _, err := executor.Run(cmd.Context(), "brew install fio"); err != nil {
+				return err
+			}
+
+			logger.Sugar().Infof("running benchmark %q on %s executor", benchmark.Name,
+				executorInitializer.Name)
+
+			stdout, err := executor.Run(cmd.Context(), benchmark.Command)
+			if err != nil {
+				return err
+			}
+
+			var fioResult Result
+
+			if err := json.Unmarshal(stdout, &fioResult); err != nil {
+				return err
+			}
+
+			if len(fioResult.Jobs) != 1 {
+				return fmt.Errorf("expected exactly 1 job from fio's JSON output, got %d",
+					len(fioResult.Jobs))
+			}
+
+			job := fioResult.Jobs[0]
+
+			readBandwidth := humanize.Bytes(uint64(job.Read.BW)*humanize.KByte) + "/s"
+			readIOPS := humanize.SIWithDigits(job.Read.IOPS, 2, "IOPS")
+
+			logger.Sugar().Infof("read bandwidth: %s, read IOPS: %s, read latency: %s",
+				readBandwidth, readIOPS, job.Read.LatencyNS.String())
+
+			writeBandwidth := humanize.Bytes(uint64(job.Write.BW)*humanize.KByte) + "/s"
+			writeIOPS := humanize.SIWithDigits(job.Write.IOPS, 2, "IOPS")
+
+			logger.Sugar().Infof("write bandwidth: %s, write IOPS: %s, write latency: %s",
+				writeBandwidth, writeIOPS, job.Write.LatencyNS.String())
+
+			logger.Sugar().Infof("sync latency: %s", job.Sync.LatencyNS.String())
+
+			table.AddRow(benchmark.Name, executorInitializer.Name, readBandwidth, writeBandwidth,
+				readIOPS, writeIOPS, job.Read.LatencyNS.String(), job.Write.LatencyNS.String(),
+				job.Sync.LatencyNS.String())
+
+			if err := executor.Close(); err != nil {
+				return fmt.Errorf("failed to close executor %s: %w",
+					executorInitializer.Name, err)
+			}
+		}
+	}
+
+	fmt.Println(table.String())
+
+	return nil
+}
@@ -0,0 +1,35 @@
+package fio
+
+import (
+	"fmt"
+	"time"
+)
+
+type Result struct {
+	Jobs []Job `json:"jobs"`
+}
+
+type Job struct {
+	Name  string `json:"jobname"`
+	Read  Stats  `json:"read"`
+	Write Stats  `json:"write"`
+	Sync  Stats  `json:"sync"`
+}
+
+type Stats struct {
+	BW        float64 `json:"bw"`
+	IOPS      float64 `json:"iops"`
+	LatencyNS Latency `json:"lat_ns"`
+}
+
+type Latency struct {
+	Mean   float64 `json:"mean"`
+	Stddev float64 `json:"stddev"`
+}
+
+func (latency Latency) String() string {
+	meanDuration := time.Duration(latency.Mean) * time.Nanosecond
+	stddevDuration := time.Duration(latency.Stddev) * time.Nanosecond
+
+	return fmt.Sprintf("%v ± %v", meanDuration, stddevDuration)
+}
@@ -0,0 +1,22 @@
+package command
+
+import (
+	"github.com/cirruslabs/tart/benchmark/internal/command/fio"
+	"github.com/cirruslabs/tart/benchmark/internal/command/xcode"
+	"github.com/spf13/cobra"
+)
+
+func NewCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "benchmark",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+
+	cmd.AddCommand(
+		fio.NewCommand(),
+		xcode.NewCommand(),
+	)
+
+	return cmd
+}
@@ -0,0 +1,13 @@
+package xcode
+
+type Benchmark struct {
+	Name    string
+	Command string
+}
+
+var benchmarks = []Benchmark{
+	{
+		Name:    "XcodeBenchmark (d869315)",
+		Command: "git clone https://github.com/devMEremenko/XcodeBenchmark.git && cd XcodeBenchmark && git reset --hard d86931529ada1df2a1c6646dd85958c360954065 && xcrun simctl list && sh benchmark.sh",
+	},
+}
@@ -0,0 +1,49 @@
+package xcode
+
+import (
+	"fmt"
+	"regexp"
+	"time"
+)
+
+type Output struct {
+	Started time.Time
+	Ended   time.Time
+}
+
+func ParseOutput(s string) (*Output, error) {
+	// Ensure that the build has succeeded
+	matched, err := regexp.MatchString("(?m)^\\*\\* BUILD SUCCEEDED \\*\\*.*$", s)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse output: regexp failed: %v", err)
+	}
+	if !matched {
+		return nil, fmt.Errorf("failed to parse output: \"** BUILD SUCCEEDED **\" string " +
+			"not found on a separate line, make sure you have Xcode installed")
+	}
+
+	re := regexp.MustCompile("Started\\s+(?P<started>.*)\\n.*Ended\\s+(?P<ended>.*)\\n")
+
+	matches := re.FindStringSubmatch(s)
+
+	if len(matches) != re.NumSubexp()+1 {
+		return nil, fmt.Errorf("failed to parse output: cannot find Started and Ended times")
+	}
+
+	startedRaw := matches[re.SubexpIndex("started")]
+	started, err := time.Parse(time.TimeOnly, startedRaw)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse started time %q: unsupported format", startedRaw)
+	}
+
+	endedRaw := matches[re.SubexpIndex("ended")]
+	ended, err := time.Parse(time.TimeOnly, endedRaw)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse ended time %q: unsupported format", startedRaw)
+	}
+
+	return &Output{
+		Started: started,
+		Ended:   ended,
+	}, nil
+}
@@ -0,0 +1,37 @@
+package xcode_test
+
+import (
+	"fmt"
+	"github.com/cirruslabs/tart/benchmark/internal/command/xcode"
+	"github.com/stretchr/testify/require"
+	"testing"
+	"time"
+)
+
+func TestParseOutput(t *testing.T) {
+	result, err := xcode.ParseOutput(`** BUILD SUCCEEDED ** [219.713 sec]
+
+System Version: 14.6
+Xcode 15.4
+Hardware Overview
+      Model Name: Apple Virtual Machine 1
+      Model Identifier: VirtualMac2,1
+      Total Number of Cores: 4
+      Memory: 8 GB
+
+✅ XcodeBenchmark has completed
+1️⃣  Take a screenshot of this window (Cmd + Shift + 4 + Space) and resize to include:
+	- Build Time (See ** BUILD SUCCEEDED ** [XYZ sec])
+	- System Version
+	- Xcode Version
+	- Hardware Overview
+	- Started 13:46:20
+	- Ended   13:50:02
+	- Date Thu Jan 16 13:50:02 UTC 2025
+
+2️⃣  Share your results at https://github.com/devMEremenko/XcodeBenchmark
+`)
+	require.NoError(t, err)
+	fmt.Println(result)
+	require.Equal(t, 222*time.Second, result.Ended.Sub(result.Started))
+}
@@ -0,0 +1,108 @@
+package xcode
+
+import (
+	"fmt"
+	executorpkg "github.com/cirruslabs/tart/benchmark/internal/executor"
+	"github.com/gosuri/uitable"
+	"github.com/spf13/cobra"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapio"
+	"os"
+	"os/exec"
+)
+
+var debug bool
+var image string
+var prepare string
+
+func NewCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "xcode",
+		Short: "run XCode benchmarks",
+		RunE:  run,
+	}
+
+	cmd.Flags().BoolVar(&debug, "debug", false, "enable debug logging")
+	cmd.Flags().StringVar(&image, "image", "ghcr.io/cirruslabs/macos-sequoia-xcode:latest", "image to use for testing")
+	cmd.Flags().StringVar(&prepare, "prepare", "", "command to run before running each benchmark")
+
+	return cmd
+}
+
+func run(cmd *cobra.Command, args []string) error {
+	config := zap.NewProductionConfig()
+	if debug {
+		config.Level = zap.NewAtomicLevelAt(zap.DebugLevel)
+	}
+	logger, err := config.Build()
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = logger.Sync()
+	}()
+
+	table := uitable.New()
+	table.AddRow("Name", "Executor", "Time")
+
+	for _, benchmark := range benchmarks {
+		for _, executorInitializer := range executorpkg.DefaultInitializers(cmd.Context(), image, logger) {
+			if prepare != "" {
+				shell := "/bin/sh"
+
+				if shellFromEnv, ok := os.LookupEnv("SHELL"); ok {
+					shell = shellFromEnv
+				}
+
+				logger.Sugar().Infof("running prepare command %q using shell %q",
+					prepare, shell)
+
+				cmd := exec.CommandContext(cmd.Context(), shell, "-c", prepare)
+
+				loggerWriter := &zapio.Writer{Log: logger, Level: zap.DebugLevel}
+
+				cmd.Stdout = loggerWriter
+				cmd.Stderr = loggerWriter
+
+				if err := cmd.Run(); err != nil {
+					return fmt.Errorf("failed to run prepare command %q: %v", prepare, err)
+				}
+			}
+
+			logger.Sugar().Infof("initializing executor %s", executorInitializer.Name)
+
+			executor, err := executorInitializer.Fn()
+			if err != nil {
+				return err
+			}
+
+			logger.Sugar().Infof("running benchmark %q on %s executor", benchmark.Name,
+				executorInitializer.Name)
+
+			stdout, err := executor.Run(cmd.Context(), benchmark.Command)
+			if err != nil {
+				return err
+			}
+
+			output, err := ParseOutput(string(stdout))
+			if err != nil {
+				return err
+			}
+
+			duration := output.Ended.Sub(output.Started)
+
+			logger.Sugar().Infof("Xcode benchmark duration: %s", duration)
+
+			table.AddRow(benchmark.Name, executorInitializer.Name, duration)
+
+			if err := executor.Close(); err != nil {
+				return fmt.Errorf("failed to close executor %s: %w",
+					executorInitializer.Name, err)
+			}
+		}
+	}
+
+	fmt.Println(table.String())
+
+	return nil
+}
@@ -0,0 +1,10 @@
+package executor
+
+import (
+	"context"
+)
+
+type Executor interface {
+	Run(ctx context.Context, command string) ([]byte, error)
+	Close() error
+}
@@ -0,0 +1,57 @@
+package executor
+
+import (
+	"context"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/local"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/tart"
+	"go.uber.org/zap"
+)
+
+type Initializer struct {
+	Name string
+	Fn   func() (Executor, error)
+}
+
+func DefaultInitializers(ctx context.Context, image string, logger *zap.Logger) []Initializer {
+	return []Initializer{
+		{
+			Name: "local",
+			Fn: func() (Executor, error) {
+				return local.New(logger)
+			},
+		},
+		{
+			Name: "Tart",
+			Fn: func() (Executor, error) {
+				return tart.New(ctx, image, nil, logger)
+			},
+		},
+		{
+			Name: "Tart (--root-disk-opts=\"sync=none\")",
+			Fn: func() (Executor, error) {
+				return tart.New(ctx, image, []string{
+					"--root-disk-opts",
+					"sync=none",
+				}, logger)
+			},
+		},
+		{
+			Name: "Tart (--root-disk-opts=\"caching=cached\")",
+			Fn: func() (Executor, error) {
+				return tart.New(ctx, image, []string{
+					"--root-disk-opts",
+					"caching=cached",
+				}, logger)
+			},
+		},
+		{
+			Name: "Tart (--root-disk-opts=\"sync=none,caching=cached\")",
+			Fn: func() (Executor, error) {
+				return tart.New(ctx, image, []string{
+					"--root-disk-opts",
+					"sync=none,caching=cached",
+				}, logger)
+			},
+		},
+	}
+}
@@ -0,0 +1,42 @@
+package local
+
+import (
+	"bytes"
+	"context"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapio"
+	"io"
+	"os/exec"
+)
+
+type Local struct {
+	logger *zap.Logger
+}
+
+func New(logger *zap.Logger) (*Local, error) {
+	return &Local{
+		logger: logger,
+	}, nil
+}
+
+func (local *Local) Name() string {
+	return "local"
+}
+
+func (local *Local) Run(ctx context.Context, command string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, "zsh", "-c", command)
+
+	loggerWriter := &zapio.Writer{Log: local.logger, Level: zap.DebugLevel}
+	stdoutBuf := &bytes.Buffer{}
+
+	cmd.Stdout = io.MultiWriter(stdoutBuf, loggerWriter)
+	cmd.Stderr = loggerWriter
+
+	err := cmd.Run()
+
+	return stdoutBuf.Bytes(), err
+}
+
+func (local *Local) Close() error {
+	return nil
+}
@@ -0,0 +1,20 @@
+package local_test
+
+import (
+	"context"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/local"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"testing"
+)
+
+func TestLocal(t *testing.T) {
+	local, err := local.New(zap.NewNop())
+	require.NoError(t, err)
+
+	output, err := local.Run(context.Background(), "echo \"this is a test\"")
+	require.NoError(t, err)
+	require.Equal(t, "this is a test\n", string(output))
+
+	require.NoError(t, local.Close())
+}
@@ -0,0 +1,35 @@
+package tart
+
+import (
+	"bytes"
+	"context"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zapio"
+	"io"
+	"os/exec"
+	"strings"
+)
+
+const tartBinaryName = "tart"
+
+func Cmd(ctx context.Context, logger *zap.Logger, args ...string) error {
+	_, err := CmdWithOutput(ctx, logger, args...)
+
+	return err
+}
+
+func CmdWithOutput(ctx context.Context, logger *zap.Logger, args ...string) (string, error) {
+	logger.Sugar().Debugf("running %s %s", tartBinaryName, strings.Join(args, " "))
+
+	cmd := exec.CommandContext(ctx, tartBinaryName, args...)
+
+	loggerWriter := &zapio.Writer{Log: logger, Level: zap.DebugLevel}
+	stdoutBuf := &bytes.Buffer{}
+
+	cmd.Stdout = io.MultiWriter(stdoutBuf, loggerWriter)
+	cmd.Stderr = loggerWriter
+
+	err := cmd.Run()
+
+	return stdoutBuf.String(), err
+}
--- a/Show More
+++ b/Show More