DiskV2: change layer size to 512 * 1024 * 1024 bytes (#866)

Needed to test https://github.com/cirruslabs/tart/pull/864.

.ci/create-pkg.sh

@@ -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" \

.ci/pkg/scripts/postinstall

@@ -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

.cirrus.yml

@@ -1,15 +1,13 @@
 use_compute_credits: true
 
-env: 
-  XCODE_TAG: 15-beta-2
-
 task:
-  name: Test on Ventura
+  name: Test on Sonoma
   alias: test
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   persistent_worker:
     labels:
       name: dev-mini
+    resources:
+      tart-vms: 1
   test_script:
     - swift test
   integration_test_script:
@@ -28,12 +26,19 @@ task:
     path: "integration-tests/pytest-junit.xml"
     format: junit
 
+task:
+  name: Markdown Lint
+  only_if: $CIRRUS_BRANCH != 'gh-pages' && changesInclude('**.md')
+  container:
+    image: node:latest
+  install_script: npm install -g markdownlint-cli
+  lint_script: markdownlint --config=docs/.markdownlint.yml docs/
+
 task:
   name: Lint
   alias: lint
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sonoma
   lint_script:
     - swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore --lint --report swiftformat.json .
   always:
@@ -43,15 +48,18 @@ task:
 
 task:
   only_if: $CIRRUS_TAG == ''
-  name: Build
+  env:
+    matrix:
+      BUILD_ARCH: arm64
+      BUILD_ARCH: x86_64
+  name: Build ($BUILD_ARCH)
   alias: build
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-ventura-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:sonoma
+  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')
@@ -59,9 +67,8 @@ task:
   depends_on:
     - lint
     - build
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sonoma
   env:
     MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
     AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
@@ -77,13 +84,13 @@ task:
     - 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:
-    - brew install go goreleaser/tap/goreleaser-pro getsentry/tools/sentry-cli
+    - brew install go goreleaser/tap/goreleaser-pro
     - brew install mitchellh/gon/gon
   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/*"
@@ -95,9 +102,8 @@ task:
     - lint
     - test
     - build
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   macos_instance:
-    image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG
+    image: ghcr.io/cirruslabs/macos-runner:sonoma
   env:
     MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2]
     AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
@@ -105,7 +111,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
@@ -142,7 +148,6 @@ task:
 task:
   name: Deploy Documentation
   only_if: $CIRRUS_BRANCH == 'main'
-  use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true'
   container:
     image: ghcr.io/cirruslabs/mkdocs-material-insiders:latest
     registry_config: ENCRYPTED[!cf1a0f25325aa75bad3ce6ebc890bc53eb0044c02efa70d8cefb83ba9766275a994b4831706c52630a0692b2fa9cfb9e!]

.gitignore

@@ -16,3 +16,6 @@ dist/
 
 # mkdocs
 .cache
+
+# mkdocs-material
+site

.goreleaser.yml

@@ -3,27 +3,35 @@ project_name: tart
 before:
   hooks:
     - .ci/set-version.sh
-    - swift build -c release --product tart
+    - swift build --arch x86_64 -c release --product tart
+    - swift build --arch arm64 -c release --product tart
     - gon gon.hcl
-    - mkdir -p tart.app/Contents/MacOS
-    - cp .build/arm64-apple-macosx/release/tart tart.app/Contents/MacOS/
 
 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'
 
 archives:
-  - name_template: "{{ .ProjectName }}"
+  - name_template: "{{ .ProjectName }}-{{ .Arch }}"
     files:
       - 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 +39,19 @@ release:
 
 brews:
   - name: tart
-    tap:
+    repository:
       owner: cirruslabs
       name: homebrew-cli
     caveats: See the GitHub repository for more information
     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 => :monterey
-      
-      on_macos do
-        unless Hardware::CPU.arm?
-          odie "Tart only works on Apple Silicon!"
-        end
-      end
+      depends_on :macos => :ventura

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to Tart
+
+Table of Contents
+-----------------
+
+- [How to Build](#how-to-build)
+- [How to Create an Issue/Enhancement](#how-to-create-an-issueenhancement)
+- [Style Guidelines](#style-guidelines)
+- [Pull Requests](#Pull-Requests)
+
+## How to Build
+
+1. Fork the repository to your own GitHub account
+2. Clone the forked repository to your local machine
+3. If using Xcode, use from Xcode 15 or newer
+4. Run ./scripts/run-signed.sh from the root of your repository
+
+```bash
+./scripts/run-signed.sh list
+```
+## How to Create an Issue/Enhancement
+
+1. Go to the [Issue page](https://github.com/cirruslabs/tart/issues) of the repository
+2. Click on the "New Issue" button
+3. Provide a descriptive title and detailed description of the issue or enhancement you're suggesting
+4. Submit the issue
+
+## Style Guidelines
+
+1. Code should follow camel case
+2. Code should follow [SwiftFormat](https://github.com/nicklockwood/SwiftFormat#swift-package-manager-plugin) guidelines. You can auto-format the code by running the following command:
+```bash
+swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore .
+```
+
+## Pull Requests
+
+1. Provide a detailed description of the changes you made in the pull request
+2. Wait for pull request to be reviewed 
+3. Make adjustments if necessary

Package.resolved

@@ -1,4 +1,5 @@
 {
+  "originHash" : "6d48639bc0ea02002de0b4f38fe3fce0ddc9d174f2e56180c2ffcbedb7391ef8",
   "pins" : [
     {
       "identity" : "antlr4",
@@ -18,13 +19,22 @@
         "revision" : "772883073d044bc754d401cabb6574624eb3778f"
       }
     },
+    {
+      "identity" : "semaphore",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/groue/Semaphore",
+      "state" : {
+        "revision" : "f1c4a0acabeb591068dea6cffdd39660b86dec28",
+        "version" : "0.0.8"
+      }
+    },
     {
       "identity" : "sentry-cocoa",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/getsentry/sentry-cocoa",
       "state" : {
-        "revision" : "d277532e1c8af813981ba01f591b15bbdd735615",
-        "version" : "8.8.0"
+        "revision" : "ef4fec9dfb8dd5027b09a4a5c9362feafd118e1a",
+        "version" : "8.24.0"
       }
     },
     {
@@ -32,8 +42,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-algorithms",
       "state" : {
-        "revision" : "b14b7f4c528c942f121c8b860b9410b2bf57825e",
-        "version" : "1.0.0"
+        "revision" : "f6919dfc309e7f1b56224378b11e28bab5bccc42",
+        "version" : "1.2.0"
       }
     },
     {
@@ -41,8 +51,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-argument-parser",
       "state" : {
-        "revision" : "f3c9084a71ef4376f2fabbdf1d3d90a49f1fabdb",
-        "version" : "1.1.2"
+        "revision" : "46989693916f56d1186bd59ac15124caef896560",
+        "version" : "1.3.1"
       }
     },
     {
@@ -59,8 +69,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/apple/swift-atomics.git",
       "state" : {
-        "revision" : "919eb1d83e02121cdb434c7bfc1f0c66ef17febe",
-        "version" : "1.0.2"
+        "revision" : "cd142fd2f64be2100422d658e7411e39489da985",
+        "version" : "1.2.0"
       }
     },
     {
@@ -72,6 +82,15 @@
         "version" : "1.0.3"
       }
     },
+    {
+      "identity" : "swift-log",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-log.git",
+      "state" : {
+        "revision" : "e97a6fcb1ab07462881ac165fdbb37f067e205d5",
+        "version" : "1.5.4"
+      }
+    },
     {
       "identity" : "swift-numerics",
       "kind" : "remoteSourceControl",
@@ -81,13 +100,22 @@
         "version" : "1.0.2"
       }
     },
+    {
+      "identity" : "swift-retry",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/fumoboy007/swift-retry",
+      "state" : {
+        "revision" : "9f133487ffc2ab4539688c29efe57bb1ba31d7b0",
+        "version" : "0.2.3"
+      }
+    },
     {
       "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"
       }
     },
     {
@@ -95,8 +123,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/malcommac/SwiftDate",
       "state" : {
-        "revision" : "6190d0cefff3013e77ed567e6b074f324e5c5bf5",
-        "version" : "6.3.1"
+        "revision" : "5d943224c3bb173e6ecf27295611615eba90c80e",
+        "version" : "7.0.0"
       }
     },
     {
@@ -104,8 +132,17 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/nicklockwood/SwiftFormat",
       "state" : {
-        "revision" : "da637c398c5d08896521b737f2868ddc2e7996ae",
-        "version" : "0.50.6"
+        "revision" : "9df3b01f477163b33d5e63c5e2e5b9f946a49c56",
+        "version" : "0.53.6"
+      }
+    },
+    {
+      "identity" : "swiftradix",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/orchetect/SwiftRadix",
+      "state" : {
+        "revision" : "a52c37a4c213403f7377ae77b4c68451bcab8330",
+        "version" : "1.3.1"
       }
     },
     {
@@ -118,5 +155,5 @@
       }
     }
   ],
-  "version" : 2
+  "version" : 3
 }

Package.swift

@@ -1,26 +1,29 @@
-// swift-tools-version:5.7
+// swift-tools-version:5.10
 
 import PackageDescription
 let package = Package(
   name: "Tart",
   platforms: [
-    .macOS(.v12)
+    .macOS(.v13)
   ],
   products: [
     .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-algorithms", from: "1.2.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/malcommac/SwiftDate", from: "7.0.0"),
     .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-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.24.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/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"),
   ],
   targets: [
     .executableTarget(name: "tart", dependencies: [
@@ -34,6 +37,9 @@ let package = Package(
       .product(name: "Sentry", package: "sentry-cocoa"),
       .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"),
     ], exclude: [
       "OCI/Reference/Makefile",
       "OCI/Reference/Reference.g4",

README.md

@@ -6,36 +6,34 @@ Built by CI engineers for your automation needs. Here are some highlights of Tar
 * Tart uses Apple's own `Virtualization.Framework` for [near-native performance](https://browser.geekbench.com/v5/cpu/compare/20382844?baseline=20382722).
 * Push/Pull virtual machines from any OCI-compatible container registry.
 * Use Tart Packer Plugin to automate VM creation.
-* Built-in CI integration.
+* Easily integrates with any CI system.
 
-*Tart* is already adopted by several automation services:
+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://cirrus-ci.org/guide/macOS/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/CirrusCI.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 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>
 
-Many more companies are using Tart in their internal setups. Here are a few of them:
+Many 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 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://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://suran.com/" target=_blank>
-    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/Users/Suran.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://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"/>
@@ -43,21 +41,30 @@ 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://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>
 </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>
+    <img src="https://github.com/cirruslabs/tart/raw/main/Resources/AWSMarkeplaceLogo.png" height="90"/>
+  </a>
+</p>
 
 ## Usage
 
-Try running a Tart VM on your Apple Silicon device running macOS 12.0 (Monterey) or later (will download a 25 GB image):
+Try running a Tart VM on your Apple Silicon device running macOS 13.0 (Ventura) or later (will download a 25 GB image):
 
 ```bash
 brew install cirruslabs/cli/tart
-tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base
-tart run ventura-base
+tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base
+tart run sonoma-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)

Resources/Info.plist

@@ -0,0 +1,23 @@
+<?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>CFBundleIdentifier</key>
+    <string>org.cirruslabs.tart</string>
+    <key>CFBundleExecutable</key>
+    <string>tart</string>
+    <key>LSBackgroundOnly</key>
+    <string>1</string>
+    <key>CFBundleIconFiles</key>
+    <array>
+        <string>AppIcon.png</string>
+    </array>
+    <key>NSAppTransportSecurity</key>
+    <dict>
+        <key>NSAllowsArbitraryLoads</key>
+        <true/>
+    </dict>
+</dict>
+</plist>

Resources/Users/HowToAddYourself.md

@@ -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.

Resources/tart-dev.entitlements

@@ -4,5 +4,7 @@
 <dict>
 	<key>com.apple.security.virtualization</key>
 	<true/>
+	<key>com.apple.security.get-task-allow</key>
+	<true/>
 </dict>
 </plist>

Sources/tart/Commands/Clone.swift

@@ -3,9 +3,22 @@ import Foundation
 import SystemConfiguration
 
 struct Clone: AsyncParsableCommand {
-  static var configuration = CommandConfiguration(abstract: "Clone a VM")
+  static var configuration = CommandConfiguration(
+    abstract: "Clone a VM",
+    discussion: """
+    Creates a local virtual machine by cloning either a remote or another local virtual machine.
 
-  @Argument(help: "source VM name")
+    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.
+
+    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.
+    """
+  )
+
+  @Argument(help: "source VM name", completion: .custom(completeMachines))
   var sourceName: String
 
   @Argument(help: "new VM name")
@@ -14,10 +27,17 @@ struct Clone: AsyncParsableCommand {
   @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
   var insecure: Bool = false
 
+  @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
+  var concurrency: UInt = 4
+
   func validate() throws {
     if newName.contains("/") {
       throw ValidationError("<new-name> should be a local name")
     }
+
+    if concurrency < 1 {
+      throw ValidationError("network concurrency cannot be less than 1")
+    }
   }
 
   func run() async throws {
@@ -27,7 +47,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)
+      try await ociStorage.pull(remoteName, registry: registry, concurrency: concurrency)
     }
 
     let sourceVM = try VMStorageHelper.open(sourceName)
@@ -43,7 +63,7 @@ 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)
@@ -53,7 +73,7 @@ struct Clone: AsyncParsableCommand {
       // 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()))
+      try Prune.reclaimIfNeeded(UInt64(sourceVM.allocatedSizeBytes()), sourceVM)
     }, onCancel: {
       try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
     })

Sources/tart/Commands/Create.swift

@@ -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")
@@ -15,13 +16,18 @@ struct Create: AsyncParsableCommand {
   @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,26 +38,32 @@ 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 {
-        if #available(macOS 13, *) {
-          _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
-        } else {
-          throw UnsupportedOSError("Linux VMs", "are")
-        }
+        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
       }
 
       try VMStorageLocal().move(name, from: tmpVMDir)

Sources/tart/Commands/Delete.swift

@@ -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 {

Sources/tart/Commands/Export.swift

@@ -4,7 +4,7 @@ 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.")

Sources/tart/Commands/FQN.swift

@@ -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)
+    }
+  }
+}

Sources/tart/Commands/Get.swift

@@ -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))
   }
 }

Sources/tart/Commands/IP.swift

@@ -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
         }
       }

Sources/tart/Commands/List.swift

@@ -5,6 +5,7 @@ import SwiftUI
 fileprivate struct VMInfo: Encodable {
   let Source: String
   let Name: String
+  let Disk: Int
   let Size: Int
   let Running: Bool
   let State: String
@@ -37,13 +38,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(), 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(), Running: vmDir.running(), State: vmDir.state().rawValue)
       })
     }
 

Sources/tart/Commands/Login.swift

@@ -17,6 +17,9 @@ struct Login: AsyncParsableCommand {
   @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
   var insecure: Bool = false
 
+  @Flag(help: "skip validation of the registry's credentials before logging-in")
+  var noValidate: Bool = false
+
   func validate() throws {
     let usernameProvided = username != nil
     let passwordProvided = passwordStdin
@@ -45,12 +48,15 @@ struct Login: AsyncParsableCommand {
       host: (user, password)
     ])
 
-    do {
+    if !noValidate {
       let registry = try Registry(host: host, namespace: "", insecure: insecure,
                                   credentialsProviders: [credentialsProvider])
-      try await registry.ping()
-    } catch {
-      throw RuntimeError.InvalidCredentials("invalid credentials: \(error)")
+
+      do {
+        try await registry.ping()
+      } catch {
+        throw RuntimeError.InvalidCredentials("invalid credentials: \(error)")
+      }
     }
 
     try KeychainCredentialsProvider().store(host: host, user: user, password: password)

Sources/tart/Commands/Logout.swift

@@ -0,0 +1,14 @@
+import ArgumentParser
+import Dispatch
+import SwiftUI
+
+struct Logout: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Logout from a registry")
+
+  @Argument(help: "host")
+  var host: String
+
+  func run() async throws {
+    try KeychainCredentialsProvider().remove(host: host)
+  }
+}

Sources/tart/Commands/Prune.swift

@@ -5,23 +5,40 @@ import SwiftUI
 import SwiftDate
 
 struct Prune: AsyncParsableCommand {
-  static var configuration = CommandConfiguration(abstract: "Prune OCI and IPSW caches")
+  static var configuration = CommandConfiguration(abstract: "Prune OCI and IPSW caches or local VMs")
 
-  @Option(help: ArgumentHelp("Remove cache entries last accessed more than n days ago",
+  @Option(help: ArgumentHelp("Entries to remove: \"caches\" targets OCI and IPSW caches and \"vms\" targets local VMs."))
+  var entries: String = "caches"
+
+  @Option(help: ArgumentHelp("Remove entries that were last accessed more than n days ago",
                              discussion: "For example, --older-than=7 will remove entries that weren't accessed by Tart in the last 7 days.",
                              valueName: "n"))
   var olderThan: UInt?
 
-  @Option(help: ArgumentHelp("Remove least recently used cache entries that do not fit the specified cache size budget n, expressed in gigabytes",
-                             discussion: "For example, --cache-budget=50 will effectively shrink all caches to a total size of 50 gigabytes.",
-                             valueName: "n"))
+  @Option(help: .hidden)
   var cacheBudget: UInt?
 
+  @Option(help: ArgumentHelp("Remove the least recently used entries that do not fit the specified space size budget n, expressed in gigabytes",
+                             discussion: "For example, --space-budget=50 will effectively shrink all entries to a total size of 50 gigabytes.",
+                             valueName: "n"))
+  var spaceBudget: UInt?
+
   @Flag(help: .hidden)
   var gc: Bool = false
 
-  func validate() throws {
-    if olderThan == nil && cacheBudget == nil && !gc {
+  mutating func validate() throws {
+    // --cache-budget deprecation logic
+    if let cacheBudget = cacheBudget {
+      fputs("--cache-budget is deprecated, please use --space-budget\n", stderr)
+
+      if spaceBudget != nil {
+        throw ValidationError("--cache-budget is deprecated, please use --space-budget")
+      }
+
+      spaceBudget = cacheBudget
+    }
+
+    if olderThan == nil && spaceBudget == nil && !gc {
       throw ValidationError("at least one pruning criteria must be specified")
     }
   }
@@ -31,43 +48,53 @@ struct Prune: AsyncParsableCommand {
       try VMStorageOCI().gc()
     }
 
+    // Build a list of prunable storages that we're going to prune based on user's request
+    let prunableStorages: [PrunableStorage]
+
+    switch entries {
+    case "caches":
+      prunableStorages = [VMStorageOCI(), try IPSWCache()]
+    case "vms":
+      prunableStorages = [VMStorageLocal()]
+    default:
+      throw ValidationError("unsupported --entries value, please specify either \"caches\" or \"vms\"")
+    }
+
     // Clean up cache entries based on last accessed date
     if let olderThan = olderThan {
       let olderThanInterval = Int(exactly: olderThan)!.days.timeInterval
       let olderThanDate = Date() - olderThanInterval
 
-      try Prune.pruneOlderThan(olderThanDate: olderThanDate)
+      try Prune.pruneOlderThan(prunableStorages: prunableStorages, olderThanDate: olderThanDate)
     }
 
     // Clean up cache entries based on imposed cache size limit and entry's last accessed date
-    if let cacheBudget = cacheBudget {
-      try Prune.pruneCacheBudget(cacheBudgetBytes: UInt64(cacheBudget) * 1024 * 1024 * 1024)
+    if let spaceBudget = spaceBudget {
+      try Prune.pruneSpaceBudget(prunableStorages: prunableStorages, spaceBudgetBytes: UInt64(spaceBudget) * 1024 * 1024 * 1024)
     }
   }
 
-  static func pruneOlderThan(olderThanDate: Date) throws {
-    let prunableStorages: [PrunableStorage] = [VMStorageOCI(), try IPSWCache()]
+  static func pruneOlderThan(prunableStorages: [PrunableStorage], olderThanDate: Date) throws {
     let prunables: [Prunable] = try prunableStorages.flatMap { try $0.prunables() }
 
     try prunables.filter { try $0.accessDate() <= olderThanDate }.forEach { try $0.delete() }
   }
 
-  static func pruneCacheBudget(cacheBudgetBytes: UInt64) throws {
-    let prunableStorages: [PrunableStorage] = [VMStorageOCI(), try IPSWCache()]
+  static func pruneSpaceBudget(prunableStorages: [PrunableStorage], spaceBudgetBytes: UInt64) throws {
     let prunables: [Prunable] = try prunableStorages
       .flatMap { try $0.prunables() }
       .sorted { try $0.accessDate() > $1.accessDate() }
 
-    var cacheBudgetBytes = cacheBudgetBytes
+    var spaceBudgetBytes = spaceBudgetBytes
     var prunablesToDelete: [Prunable] = []
 
     for prunable in prunables {
-      let prunableSizeBytes = UInt64(try prunable.sizeBytes())
+      let prunableSizeBytes = UInt64(try prunable.allocatedSizeBytes())
 
-      if prunableSizeBytes <= cacheBudgetBytes {
+      if prunableSizeBytes <= spaceBudgetBytes {
         // Don't mark for deletion as
         // there's a budget available
-        cacheBudgetBytes -= prunableSizeBytes
+        spaceBudgetBytes -= prunableSizeBytes
       } else {
         // Mark for deletion
         prunablesToDelete.append(prunable)
@@ -77,7 +104,11 @@ struct Prune: AsyncParsableCommand {
     try prunablesToDelete.forEach { try $0.delete() }
   }
 
-  static func reclaimIfNeeded(_ requiredBytes: UInt64) throws {
+  static func reclaimIfNeeded(_ requiredBytes: UInt64, _ initiator: Prunable? = nil) throws {
+    if ProcessInfo.processInfo.environment.keys.contains("TART_NO_AUTO_PRUNE") {
+      return
+    }
+
     SentrySDK.configureScope { scope in
       scope.setContext(value: ["requiredBytes": requiredBytes], key: "Prune")
     }
@@ -114,10 +145,10 @@ struct Prune: AsyncParsableCommand {
       return
     }
 
-    try Prune.reclaimIfPossible(requiredBytes - volumeAvailableCapacityCalculated)
+    try Prune.reclaimIfPossible(requiredBytes - volumeAvailableCapacityCalculated, initiator)
   }
 
-  private static func reclaimIfPossible(_ reclaimBytes: UInt64) throws {
+  private static func reclaimIfPossible(_ reclaimBytes: UInt64, _ initiator: Prunable? = nil) throws {
     let transaction = SentrySDK.startTransaction(name: "Pruning cache", operation: "prune", bindToScope: true)
     defer { transaction.finish() }
 
@@ -127,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
     }
@@ -141,9 +172,14 @@ struct Prune: AsyncParsableCommand {
         break
       }
 
-      try SentrySDK.span?.setData(value: prunable.sizeBytes(), key: prunable.url.path)
+      if prunable.url == initiator?.url.resolvingSymlinksInPath() {
+        // do not prune the initiator
+        continue
+      }
 
-      cacheReclaimedBytes += try prunable.sizeBytes()
+      try SentrySDK.span?.setData(value: prunable.allocatedSizeBytes(), key: prunable.url.path)
+
+      cacheReclaimedBytes += try prunable.allocatedSizeBytes()
 
       try prunable.delete()
     }

Sources/tart/Commands/Pull.swift

@@ -3,7 +3,16 @@ import Dispatch
 import SwiftUI
 
 struct Pull: AsyncParsableCommand {
-  static var configuration = CommandConfiguration(abstract: "Pull a VM from a registry")
+  static var configuration = CommandConfiguration(
+    abstract: "Pull a VM from a registry",
+    discussion: """
+    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.
+    """
+  )
 
   @Argument(help: "remote VM name")
   var remoteName: String
@@ -11,6 +20,15 @@ struct Pull: AsyncParsableCommand {
   @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
   var insecure: Bool = false
 
+  @Option(help: "network concurrency to use when pulling a remote VM from the OCI-compatible registry")
+  var concurrency: UInt = 4
+
+  func validate() throws {
+    if concurrency < 1 {
+      throw ValidationError("network concurrency cannot be less than 1")
+    }
+  }
+
   func run() async throws {
     // Be more liberal when accepting local image as argument,
     // see https://github.com/cirruslabs/tart/issues/36
@@ -25,6 +43,6 @@ struct Pull: AsyncParsableCommand {
 
     defaultLogger.appendNewLine("pulling \(remoteName)...")
 
-    try await VMStorageOCI().pull(remoteName, registry: registry)
+    try await VMStorageOCI().pull(remoteName, registry: registry, concurrency: concurrency)
   }
 }

Sources/tart/Commands/Push.swift

@@ -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)")
@@ -23,6 +23,9 @@ struct Push: AsyncParsableCommand {
                              """))
   var chunkSize: Int = 0
 
+  @Option(help: .hidden)
+  var diskFormat: String = "v2"
+
   @Flag(help: ArgumentHelp("cache pushed images locally",
                            discussion: "Increases disk usage, but saves time if you're going to pull the pushed images later."))
   var populateCache: Bool = false
@@ -30,6 +33,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{
@@ -69,7 +76,8 @@ struct Push: AsyncParsableCommand {
         pushedRemoteName = try await localVMDir.pushToRegistry(
           registry: registry,
           references: references,
-          chunkSizeMb: chunkSize
+          chunkSizeMb: chunkSize,
+          diskFormat: diskFormat
         )
         // Populate the local cache (if requested)
         if populateCache {

Sources/tart/Commands/Rename.swift

@@ -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)

Sources/tart/Commands/Run.swift

@@ -1,9 +1,11 @@
 import ArgumentParser
 import Cocoa
+import Darwin
 import Dispatch
 import SwiftUI
 import Virtualization
 import Sentry
+import System
 
 var vm: VM?
 
@@ -13,7 +15,7 @@ struct IPNotFound: Error {
 struct Run: AsyncParsableCommand {
   static var configuration = CommandConfiguration(abstract: "Run a VM")
 
-  @Argument(help: "VM name")
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
   var name: String
 
   @Flag(help: ArgumentHelp(
@@ -32,54 +34,87 @@ struct Run: AsyncParsableCommand {
   ))
   var serialPath: String?
 
-  @Flag(help: "Force open a UI window, even when VNC is enabled.")
+  @Flag(help: ArgumentHelp("Force open a UI window, even when VNC is enabled.", visibility: .private))
   var graphics: Bool = false
 
-  @Flag(help: "Boot into recovery mode")
+  @Flag(help: "Disable audio pass-through to host.")
+  var noAudio: Bool = false
+
+  @Flag(help: ArgumentHelp(
+    "Disable clipboard sharing between host and guest.",
+    discussion: "Only works with Linux-based guest operating systems."))
+  var noClipboard: Bool = false
+
+  #if arch(arm64)
+    @Flag(help: "Boot into recovery mode")
+  #endif
   var recovery: Bool = false
 
-  @Flag(help: ArgumentHelp(
-    "Use screen sharing instead of the built-in UI.",
-    discussion: "Useful since Screen Sharing supports copy/paste, drag and drop, etc.\n"
-      + "Note that Remote Login option should be enabled inside the VM."))
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp(
+      "Use screen sharing instead of the built-in UI.",
+      discussion: "Useful since Screen Sharing supports copy/paste, drag and drop, etc.\n"
+        + "Note that Remote Login option should be enabled inside the VM."))
+  #endif
   var vnc: Bool = false
 
-  @Flag(help: ArgumentHelp(
-    "Use Virtualization.Framework's VNC server instead of the build-in UI.",
-    discussion: "Useful since this type of VNC is available in recovery mode and in macOS installation.\n"
-      + "Note that this feature is experimental and there may be bugs present when using VNC."))
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp(
+      "Use Virtualization.Framework's VNC server instead of the built-in UI.",
+      discussion: "Useful since this type of VNC is available in recovery mode and in macOS installation.\n"
+        + "Note that this feature is experimental and there may be bugs present when using VNC."))
+  #endif
   var vncExperimental: Bool = false
 
   @Option(help: ArgumentHelp("""
-  Additional disk attachments with an optional read-only specifier\n(e.g. --disk=\"disk.bin\" --disk=\"ubuntu.iso:ro\")
+  Additional disk attachments with an optional read-only specifier\n(e.g. --disk=\"disk.bin\" --disk=\"ubuntu.iso:ro\" --disk=\"/dev/disk0\" --disk "ghcr.io/cirruslabs/xcode:16.0:ro" --disk=\"nbd://localhost:10809/myDisk\")
   """, discussion: """
-  Learn how to create a disk image using Disk Utility here:
-  https://support.apple.com/en-gb/guide/disk-utility/dskutl11888/mac
+  The disk attachment can be a:
+
+  * path to a disk image file
+  * path to a block device (for example, a local SSD on AWS EC2 Mac instances)
+  * remote VM name whose disk will be mounted
+  * Network Block Device (NBD) URL
+
+  Learn how to create a disk image using Disk Utility here: https://support.apple.com/en-gb/guide/disk-utility/dskutl11888/mac
+
+  To work with block devices, the easiest way is to modify their permissions (e.g. by using "sudo chown $USER /dev/diskX") or to run the Tart binary as root, which affects locating Tart VMs.
+
+  To work around this pass TART_HOME explicitly:
+
+  sudo TART_HOME="$HOME/.tart" tart run sonoma --disk=/dev/disk0
   """, valueName: "path[:ro]"))
   var disk: [String] = []
 
-  @Option(name: [.customLong("rosetta")], help: ArgumentHelp(
-    "Attaches a Rosetta share to the guest Linux VM with a specific tag (e.g. --rosetta=\"rosetta\")",
-    discussion: """
-    Requires host to be macOS 13.0 (Ventura) with Rosetta installed. The latter can be done
-    by running "softwareupdate --install-rosetta" (without quotes) in the Terminal.app.
+  #if arch(arm64)
+    @Option(name: [.customLong("rosetta")], help: ArgumentHelp(
+      "Attaches a Rosetta share to the guest Linux VM with a specific tag (e.g. --rosetta=\"rosetta\")",
+      discussion: """
+      Requires host to be macOS 13.0 (Ventura) with Rosetta installed. The latter can be done
+      by running "softwareupdate --install-rosetta" (without quotes) in the Terminal.app.
 
-    Note that you also have to configure Rosetta in the guest Linux VM by following the
-    steps from "Mount the Shared Directory and Register Rosetta" section here:
-    https://developer.apple.com/documentation/virtualization/running_intel_binaries_in_linux_vms_with_rosetta#3978496
-    """,
-    valueName: "tag"
-  ))
+      Note that you also have to configure Rosetta in the guest Linux VM by following the
+      steps from "Mount the Shared Directory and Register Rosetta" section here:
+      https://developer.apple.com/documentation/virtualization/running_intel_binaries_in_linux_vms_with_rosetta#3978496
+      """,
+      valueName: "tag"
+    ))
+  #endif
   var rosettaTag: String?
 
-  @Option(help: ArgumentHelp("""
-  Additional directory shares with an optional read-only specifier\n(e.g. --dir=\"build:~/src/build\" --dir=\"sources:~/src/sources:ro\")
-  """, discussion: """
-  Requires host to be macOS 13.0 (Ventura) or newer.
-  All shared directories are automatically mounted to "/Volumes/My Shared Files" directory on macOS,
-  while on Linux you have to do it manually: "mount -t virtiofs com.apple.virtio-fs.automount /mount/point".
-  For macOS guests, they must be running macOS 13.0 (Ventura) or newer.
-  """, valueName: "name:path[:ro]"))
+  @Option(help: ArgumentHelp("Additional directory shares with an optional read-only and mount tag options (e.g. --dir=\"~/src/build\" or --dir=\"~/src/sources:ro\")", discussion: """
+  Requires host to be macOS 13.0 (Ventura) or newer. macOS guests must be running macOS 13.0 (Ventura) or newer too.
+
+  Options are comma-separated and are as follows:
+
+  * ro — mount this directory share in read-only mode instead of the default read-write (e.g. --dir=\"~/src/sources:ro\")
+
+  * tag=<TAG> — by default, the \"com.apple.virtio-fs.automount\" mount tag is used for all directory shares. On macOS, this causes the directories to be automatically mounted to "/Volumes/My Shared Files" directory. On Linux, you have to do it manually: "mount -t virtiofs com.apple.virtio-fs.automount /mount/point".
+
+  Mount tag can be overridden by appending tag property to the directory share (e.g. --dir=\"~/src/build:tag=build\" or --dir=\"~/src/build:ro,tag=build\"). Then it can be mounted via "mount_virtiofs build ~/build" inside guest macOS and "mount -t virtiofs build ~/build" inside guest Linux.
+
+  In case of passing multiple directories per mount tag it is required to prefix them with names e.g. --dir=\"build:~/src/build\" --dir=\"sources:~/src/sources:ro\". These names will be used as directory names under the mounting point inside guests. For the example above it will be "/Volumes/My Shared Files/build" and "/Volumes/My Shared Files/sources" respectively.
+  """, valueName: "[name:]path[:options]"))
   var dir: [String] = []
 
   @Option(help: ArgumentHelp("""
@@ -87,33 +122,73 @@ struct Run: AsyncParsableCommand {
   """, discussion: """
   Specify "list" as an interface name (--net-bridged=list) to list the available bridged interfaces.
   """, valueName: "interface name"))
-  var netBridged: String?
+  var netBridged: [String] = []
 
   @Flag(help: ArgumentHelp("Use software networking instead of the default shared (NAT) networking",
                            discussion: "Learn how to configure Softnet for use with Tart here: https://github.com/cirruslabs/softnet"))
   var netSoftnet: Bool = false
 
-  @Flag(help: ArgumentHelp("Disables audio and entropy devices and switches to only Mac-specific input devices.", discussion: "Useful for running a VM that can be suspended via \"tart suspend\"."))
+  @Option(help: ArgumentHelp("Comma-separated list of CIDRs to allow the traffic to when using Softnet isolation\n(e.g. --net-softnet-allow=192.168.0.0/24)", valueName: "comma-separated CIDRs"))
+  var netSoftnetAllow: String?
+
+  @Flag(help: ArgumentHelp("Restrict network access to the host-only network"))
+  var netHost: Bool = false
+
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp("Disables audio and entropy devices and switches to only Mac-specific input devices.", discussion: "Useful for running a VM that can be suspended via \"tart suspend\"."))
+  #endif
   var suspendable: Bool = false
 
+  #if arch(arm64)
+    @Flag(help: ArgumentHelp("Whether system hot keys should be sent to the guest instead of the host",
+                             discussion: "If enabled then system hot keys like Cmd+Tab will be sent to the guest instead of the host."))
+  #endif
+  var captureSystemKeys: Bool = false
+
   mutating func validate() throws {
     if vnc && vncExperimental {
       throw ValidationError("--vnc and --vnc-experimental are mutually exclusive")
     }
 
-    if netBridged != nil && netSoftnet {
-      throw ValidationError("--net-bridged and --net-softnet are mutually exclusive")
+    // check that not more than one network option is specified
+    var netFlags = 0
+    if netBridged.count > 0 { netFlags += 1 }
+    if netSoftnet { netFlags += 1 }
+    if netHost { netFlags += 1 }
+
+    if netFlags > 1 {
+      throw ValidationError("--net-bridged, --net-softnet and --net-host are mutually exclusive")
     }
 
     if graphics && noGraphics {
       throw ValidationError("--graphics and --no-graphics are mutually exclusive")
     }
 
+    if (noGraphics || vnc || vncExperimental) && captureSystemKeys {
+      throw ValidationError("--captures-system-keys can only be used with the default VM view")
+    }
+
     let localStorage = VMStorageLocal()
     let vmDir = try localStorage.open(name)
-    if try vmDir.state() == "suspended" {
+    if try vmDir.state() == .Suspended {
       suspendable = true
     }
+
+    if suspendable {
+      let config = try VMConfig.init(fromURL: vmDir.configURL)
+      if (config.platform is Linux) {
+        throw ValidationError("You can only suspend macOS VMs")
+      }
+      if dir.count > 0 {
+        throw ValidationError("Suspending VMs with shared directories is not supported")
+      }
+    }
+
+    for disk in disk {
+      if disk.hasSuffix("-amd64.iso") {
+        throw ValidationError("Seems you have a disk targeting x86 architecture (hence amd64 in the name). Please use an 'arm64' version of the disk.")
+      }
+    }
   }
 
   @MainActor
@@ -122,40 +197,24 @@ struct Run: AsyncParsableCommand {
     let vmDir = try localStorage.open(name)
 
     let storageLock = try FileLock(lockURL: Config().tartHomeDir)
-    if try vmDir.state() == "suspended" {
-      try storageLock.lock() // lock before checking
-      let needToGenerateNewMac = try localStorage.list().contains {
-        // check if there is a running VM with the same MAC but different name
-        try $1.running() && $1.macAddress() == vmDir.macAddress() && $1.name != vmDir.name
-      }
-
-      if needToGenerateNewMac {
-        print("There is already a running VM with the same MAC address!")
-        print("Resetting VM to assign a new MAC address...")
-        try vmDir.regenerateMACAddress()
-      }
+    try storageLock.lock()
+    // check if there is a running VM with the same MAC address
+    let hasRunningMACCollision = try localStorage.list().contains {
+      // check if there is a running VM with the same MAC but different name
+      try $1.running() && $1.macAddress() == vmDir.macAddress() && $1.name != vmDir.name
+    }
+    if hasRunningMACCollision {
+      print("There is already a running VM with the same MAC address!")
+      print("Resetting VM to assign a new MAC address...")
+      try vmDir.regenerateMACAddress()
     }
 
-    if netSoftnet && isInteractiveSession() {
+    if (netSoftnet || netHost) && isInteractiveSession() {
       try Softnet.configureSUIDBitIfNeeded()
     }
 
     let additionalDiskAttachments = try additionalDiskAttachments()
 
-    // Error out if the disk is locked by the host (e.g. it was mounted in Finder),
-    // see https://github.com/cirruslabs/tart/issues/323 for more details.
-    for additionalDiskAttachment in additionalDiskAttachments {
-      // Read-only attachments do not seem to acquire the lock
-      if additionalDiskAttachment.isReadOnly {
-        continue
-      }
-
-      if try !FileLock(lockURL: additionalDiskAttachment.url).trylock() {
-        throw RuntimeError.DiskAlreadyInUse("disk \(additionalDiskAttachment.url.path) seems to be already in use, "
-          + "unmount it first in Finder")
-      }
-    }
-
     var serialPorts: [VZSerialPortConfiguration] = []
     if serial {
       let tty_fd = createPTY()
@@ -177,10 +236,12 @@ struct Run: AsyncParsableCommand {
     vm = try VM(
       vmDir: vmDir,
       network: userSpecifiedNetwork(vmDir: vmDir) ?? NetworkShared(),
-      additionalDiskAttachments: additionalDiskAttachments,
+      additionalStorageDevices: additionalDiskAttachments,
       directorySharingDevices: directoryShares() + rosettaDirectoryShare(),
       serialPorts: serialPorts,
-      suspendable: suspendable
+      suspendable: suspendable,
+      audio: !noAudio,
+      clipboard: !noClipboard
     )
 
     let vncImpl: VNC? = try {
@@ -206,7 +267,7 @@ struct Run: AsyncParsableCommand {
     // configuration file, otherwise we will loose the lock.
     //
     // [1]: https://man.openbsd.org/fcntl
-    let lock = try PIDLock(lockURL: vmDir.configURL)
+    let lock = try vmDir.lock()
     if try !lock.trylock() {
       throw RuntimeError.VMAlreadyRunning("VM \"\(name)\" is already running!")
     }
@@ -216,8 +277,24 @@ struct Run: AsyncParsableCommand {
 
     let task = Task {
       do {
+        var resume = false
+
+        #if arch(arm64)
+          if #available(macOS 14, *) {
+            if FileManager.default.fileExists(atPath: vmDir.stateURL.path) {
+              print("restoring VM state from a snapshot...")
+              try await vm!.virtualMachine.restoreMachineStateFrom(url: vmDir.stateURL)
+              try FileManager.default.removeItem(at: vmDir.stateURL)
+              resume = true
+              print("resuming VM...")
+            }
+          }
+        #endif
+
+        try await vm!.start(recovery: recovery, resume: resume)
+
         if let vncImpl = vncImpl {
-          let vncURL = try await vncImpl.waitForURL()
+          let vncURL = try await vncImpl.waitForURL(netBridged: !netBridged.isEmpty)
 
           if noGraphics || ProcessInfo.processInfo.environment["CI"] != nil {
             print("VNC server is running at \(vncURL)")
@@ -227,19 +304,7 @@ struct Run: AsyncParsableCommand {
           }
         }
 
-        var resume = false
-
-        if #available(macOS 14, *) {
-          if FileManager.default.fileExists(atPath: vmDir.stateURL.path) {
-            print("restoring VM state from a snapshot...")
-            try await vm!.virtualMachine.restoreMachineStateFrom(url: vmDir.stateURL)
-            try FileManager.default.removeItem(at: vmDir.stateURL)
-            resume = true
-            print("resuming VM...")
-          }
-        }
-
-        try await vm!.run(recovery: recovery, resume: resume)
+        try await vm!.run()
 
         if let vncImpl = vncImpl {
           try vncImpl.stop()
@@ -270,23 +335,25 @@ struct Run: AsyncParsableCommand {
     sigusr1Src.setEventHandler {
       Task {
         do {
-          if #available(macOS 14, *) {
-            try vm!.configuration.validateSaveRestoreSupport()
+          #if arch(arm64)
+            if #available(macOS 14, *) {
+              try vm!.configuration.validateSaveRestoreSupport()
 
-            print("pausing VM to take a snapshot...")
-            try await vm!.virtualMachine.pause()
+              print("pausing VM to take a snapshot...")
+              try await vm!.virtualMachine.pause()
 
-            print("creating a snapshot...")
-            try await vm!.virtualMachine.saveMachineStateTo(url: vmDir.stateURL)
+              print("creating a snapshot...")
+              try await vm!.virtualMachine.saveMachineStateTo(url: vmDir.stateURL)
 
-            print("snapshot created successfully! shutting down the VM...")
+              print("snapshot created successfully! shutting down the VM...")
 
-            task.cancel()
-          } else {
-            print(RuntimeError.SuspendFailed("this functionality is only supported on macOS 14 (Sonoma) or newer"))
+              task.cancel()
+            } else {
+              print(RuntimeError.SuspendFailed("this functionality is only supported on macOS 14 (Sonoma) or newer"))
 
-            Foundation.exit(1)
-          }
+              Foundation.exit(1)
+            }
+          #endif
         } catch (let e) {
           print(RuntimeError.SuspendFailed(e.localizedDescription))
 
@@ -296,11 +363,25 @@ struct Run: AsyncParsableCommand {
     }
     sigusr1Src.activate()
 
+    // Gracefull shutdown support. For macOS this brings up a dialog,
+    // asking the user if they are sure they want to shut down.
+    signal(SIGUSR2, SIG_IGN)
+    let sigusr2Src = DispatchSource.makeSignalSource(signal: SIGUSR2)
+    sigusr2Src.setEventHandler {
+      Task {
+        print("Requesting guest OS to stop...")
+        try vm!.virtualMachine.requestStop()
+      }
+    }
+    sigusr2Src.activate()
+
     let useVNCWithoutGraphics = (vnc || vncExperimental) && !graphics
     if noGraphics || useVNCWithoutGraphics {
-      dispatchMain()
+      // enter the main even loop, without bringing up any UI,
+      // and just wait for the VM to exit.
+      NSApplication.shared.run()
     } else {
-      runUI(suspendable)
+      runUI(suspendable, captureSystemKeys)
     }
   }
 
@@ -319,29 +400,37 @@ struct Run: AsyncParsableCommand {
   }
 
   func userSpecifiedNetwork(vmDir: VMDirectory) throws -> Network? {
+    var softnetExtraArguments: [String] = []
+
+    if let netSoftnetAllow = netSoftnetAllow {
+      softnetExtraArguments += ["--allow", netSoftnetAllow]
+    }
+
     if netSoftnet {
       let config = try VMConfig.init(fromURL: vmDir.configURL)
 
-      return try Softnet(vmMACAddress: config.macAddress.string)
+      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: softnetExtraArguments)
     }
 
-    if let netBridged = netBridged {
-      let matchingInterfaces = VZBridgedNetworkInterface.networkInterfaces.filter { interface in
-        interface.identifier == netBridged || interface.localizedDisplayName == netBridged
+    if netHost {
+      let config = try VMConfig.init(fromURL: vmDir.configURL)
+
+      return try Softnet(vmMACAddress: config.macAddress.string, extraArguments: ["--vm-net-type", "host"] + softnetExtraArguments)
+    }
+
+    if netBridged.count > 0 {
+      func findBridgedInterface(_ name: String) throws -> VZBridgedNetworkInterface {
+        let interface = VZBridgedNetworkInterface.networkInterfaces.first { interface in
+          interface.identifier == name || interface.localizedDisplayName == name
+        }
+        if (interface == nil) {
+          throw ValidationError("no bridge interfaces matched \"\(netBridged)\", "
+            + "available interfaces: \(bridgeInterfaces())")
+        }
+        return interface!
       }
 
-      if matchingInterfaces.isEmpty {
-        let available = bridgeInterfaces().joined(separator: ", ")
-        throw ValidationError("no bridge interfaces matched \"\(netBridged)\", "
-          + "available interfaces: \(available)")
-      }
-
-      if matchingInterfaces.count > 1 {
-        throw ValidationError("more than one bridge interface matched \"\(netBridged)\", "
-          + "consider refining the search criteria")
-      }
-
-      return NetworkBridged(interface: matchingInterfaces.first!)
+      return NetworkBridged(interfaces: try netBridged.map { try findBridgedInterface($0) })
     }
 
     return nil
@@ -359,23 +448,88 @@ struct Run: AsyncParsableCommand {
     }
   }
 
-  func additionalDiskAttachments() throws -> [VZDiskImageStorageDeviceAttachment] {
-    var result: [VZDiskImageStorageDeviceAttachment] = []
+  func additionalDiskAttachments() throws -> [VZStorageDeviceConfiguration] {
+    var result: [VZStorageDeviceConfiguration] = []
     let readOnlySuffix = ":ro"
     let expandedDiskPaths = disk.map { NSString(string:$0).expandingTildeInPath }
 
     for rawDisk in expandedDiskPaths {
-      if rawDisk.hasSuffix(readOnlySuffix) {
-        result.append(try VZDiskImageStorageDeviceAttachment(
-          url: URL(fileURLWithPath: String(rawDisk.prefix(rawDisk.count - readOnlySuffix.count))),
-          readOnly: true
-        ))
-      } else {
-        result.append(try VZDiskImageStorageDeviceAttachment(
-          url: URL(fileURLWithPath: rawDisk),
-          readOnly: false
-        ))
+      let diskReadOnly = rawDisk.hasSuffix(readOnlySuffix)
+      let diskPath = diskReadOnly ? String(rawDisk.prefix(rawDisk.count - readOnlySuffix.count)) : rawDisk
+
+      let diskURL = URL(string: diskPath)
+      if (["nbd", "nbds", "nbd+unix", "nbds+unix"].contains(diskURL?.scheme)) {
+        guard #available(macOS 14, *) else {
+          throw UnsupportedOSError("attaching Network Block Devices", "are")
+        }
+
+        let nbdAttachment = try VZNetworkBlockDeviceStorageDeviceAttachment(
+          url: diskURL!,
+          timeout: 30,
+          isForcedReadOnly: diskReadOnly,
+          synchronizationMode: VZDiskSynchronizationMode.none
+        )
+        result.append(VZVirtioBlockDeviceConfiguration(attachment: nbdAttachment))
+        continue
       }
+
+      let diskFileURL = URL(fileURLWithPath: diskPath)
+
+      if pathHasMode(diskPath, mode: S_IFBLK) {
+        guard #available(macOS 14, *) else {
+          throw UnsupportedOSError("attaching block devices", "are")
+        }
+
+        let fd = open(diskPath, diskReadOnly ? O_RDONLY : O_RDWR)
+        if fd == -1 {
+          let details = Errno(rawValue: CInt(errno))
+
+          switch details.rawValue {
+          case EBUSY:
+            throw RuntimeError.FailedToOpenBlockDevice(diskFileURL.url.path, "already in use, try umounting it via \"diskutil unmountDisk\" (when the whole disk) or \"diskutil umount\" (when mounting a single partition)")
+          case EACCES:
+            throw RuntimeError.FailedToOpenBlockDevice(diskFileURL.url.path, "permission denied, consider changing the disk's owner using \"sudo chown $USER \(diskFileURL.url.path)\" or run Tart as a superuser (see --disk help for more details on how to do that correctly)")
+          default:
+            throw RuntimeError.FailedToOpenBlockDevice(diskFileURL.url.path, "\(details)")
+          }
+        }
+
+        let blockAttachment = try VZDiskBlockDeviceStorageDeviceAttachment(fileHandle: FileHandle(fileDescriptor: fd, closeOnDealloc: true),
+                                                                           readOnly: diskReadOnly, synchronizationMode: .full)
+        result.append(VZVirtioBlockDeviceConfiguration(attachment: blockAttachment))
+        continue
+      }
+
+      // Support remote VM names in --disk command-line argument
+      if let remoteName = try? RemoteName(diskPath) {
+        let vmDir = try VMStorageOCI().open(remoteName)
+
+        // Unfortunately, VZDiskImageStorageDeviceAttachment does not support
+        // FileHandle, so we can't easily clone the disk, open it and unlink(2)
+        // to simplify the garbage collection, so use an intermediate directory.
+        let clonedDiskURL = try Config().tartTmpDir.appendingPathComponent("run-disk-\(UUID().uuidString)")
+
+        try FileManager.default.copyItem(at: vmDir.diskURL, to: clonedDiskURL)
+
+        let lock = try FileLock(lockURL: clonedDiskURL)
+        try lock.lock()
+
+        let diskImageAttachment = try VZDiskImageStorageDeviceAttachment(url: clonedDiskURL, readOnly: diskReadOnly)
+        result.append(VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment))
+        continue
+      }
+
+      // Error out if the disk is locked by the host (e.g. it was mounted in Finder),
+      // see https://github.com/cirruslabs/tart/issues/323 for more details.
+      if try !diskReadOnly && !FileLock(lockURL: diskFileURL).trylock() {
+        throw RuntimeError.DiskAlreadyInUse("disk \(diskFileURL.url.path) seems to be already in use, unmount it first in Finder")
+      }
+
+      let diskImageAttachment = try VZDiskImageStorageDeviceAttachment(
+        url: diskFileURL,
+        readOnly: diskReadOnly
+      )
+      result.append(VZVirtioBlockDeviceConfiguration(attachment: diskImageAttachment))
     }
 
     return result
@@ -390,141 +544,130 @@ struct Run: AsyncParsableCommand {
       throw UnsupportedOSError("directory sharing", "is")
     }
 
-    struct DirectoryShare {
-      let name: String
-      let path: URL
-      let readOnly: Bool
-    }
-
-    var directoryShares: [DirectoryShare] = []
+    var allDirectoryShares: [DirectoryShare] = []
 
     for rawDir in dir {
-      let splits = rawDir.split(maxSplits: 2) { $0 == ":" }
-
-      if splits.count < 2 {
-        throw ValidationError("invalid --dir syntax: should at least include name and path, colon-separated")
-      }
-
-      var readOnly: Bool = false
-
-      if splits.count == 3 {
-        if splits[2] == "ro" {
-          readOnly = true
-        } else {
-          throw ValidationError("invalid --dir syntax: optional read-only specifier can only be \"ro\"")
-        }
-      }
-
-      let (name, path) = (String(splits[0]), String(splits[1]))
-
-      directoryShares.append(DirectoryShare(
-        name: name,
-        path: URL(fileURLWithPath: NSString(string: path).expandingTildeInPath),
-        readOnly: readOnly)
-      )
+      allDirectoryShares.append(try DirectoryShare(parseFrom: rawDir))
     }
 
-    var directories: [String : VZSharedDirectory] = Dictionary()
-    directoryShares.forEach { directories[$0.name] = VZSharedDirectory(url: $0.path, readOnly: $0.readOnly) }
+    return try Dictionary(grouping: allDirectoryShares, by: {$0.mountTag}).map { mountTag, directoryShares in
+      let sharingDevice = VZVirtioFileSystemDeviceConfiguration(tag: mountTag)
 
-    let automountTag = VZVirtioFileSystemDeviceConfiguration.macOSGuestAutomountTag
-    let sharingDevice = VZVirtioFileSystemDeviceConfiguration(tag: automountTag)
-    sharingDevice.share = VZMultipleDirectoryShare(directories: directories)
+      var allNamedShares = true
+      for directoryShare in directoryShares {
+        if directoryShare.name == nil {
+          allNamedShares = false
+        }
+      }
+      if directoryShares.count == 1 && directoryShares.first!.name == nil {
+        let directoryShare = directoryShares.first!
+        let singleDirectoryShare = VZSingleDirectoryShare(directory: try directoryShare.createConfiguration())
+        sharingDevice.share = singleDirectoryShare
+      } else if !allNamedShares {
+        throw ValidationError("invalid --dir syntax: for multiple directory shares each one of them should be named")
+      } else {
+        var directories: [String : VZSharedDirectory] = Dictionary()
+        try directoryShares.forEach { directories[$0.name!] = try $0.createConfiguration() }
+        sharingDevice.share = VZMultipleDirectoryShare(directories: directories)
+      }
 
-    return [sharingDevice]
+      return sharingDevice
+    }
   }
 
   private func rosettaDirectoryShare() throws -> [VZDirectorySharingDeviceConfiguration] {
     guard let rosettaTag = rosettaTag else {
       return []
     }
+    #if arch(arm64)
+      guard #available(macOS 13, *) else {
+        throw UnsupportedOSError("Rosetta directory share", "is")
+      }
 
-    guard #available(macOS 13, *) else {
-      throw UnsupportedOSError("Rosetta directory share", "is")
-    }
+      switch VZLinuxRosettaDirectoryShare.availability {
+      case .notInstalled:
+        throw UnsupportedOSError("Rosetta directory share", "is", "that have Rosetta installed")
+      case .notSupported:
+        throw UnsupportedOSError("Rosetta directory share", "is", "running Apple silicon")
+      default:
+        break
+      }
 
-    switch VZLinuxRosettaDirectoryShare.availability {
-    case .notInstalled:
-      throw UnsupportedOSError("Rosetta directory share", "is", "that have Rosetta installed")
-    case .notSupported:
-      throw UnsupportedOSError("Rosetta directory share", "is", "running Apple silicon")
-    default:
-      break
-    }
+      try VZVirtioFileSystemDeviceConfiguration.validateTag(rosettaTag)
+      let device = VZVirtioFileSystemDeviceConfiguration(tag: rosettaTag)
+      device.share = try VZLinuxRosettaDirectoryShare()
 
-    try VZVirtioFileSystemDeviceConfiguration.validateTag(rosettaTag)
-    let device = VZVirtioFileSystemDeviceConfiguration(tag: rosettaTag)
-    device.share = try VZLinuxRosettaDirectoryShare()
-
-    return [device]
+      return [device]
+    #elseif arch(x86_64)
+      // there is no Rosetta on Intel
+      return []
+    #endif
   }
 
-  private func runUI(_ suspendable: Bool) {
-    let nsApp = NSApplication.shared
-    nsApp.setActivationPolicy(.regular)
-    nsApp.activate(ignoringOtherApps: true)
+  private func runUI(_ suspendable: Bool, _ captureSystemKeys: Bool) {
+    MainApp.suspendable = suspendable
+    MainApp.capturesSystemKeys = captureSystemKeys
+    MainApp.main()
+  }
+}
 
-    nsApp.applicationIconImage = NSImage(data: AppIconData)
+struct MainApp: App {
+  static var suspendable: Bool = false
+  static var capturesSystemKeys: Bool = false
 
-    struct MainApp: App {
-      static var disappearSignal: Int32 = SIGINT
+  @NSApplicationDelegateAdaptor private var appDelegate: MinimalMenuAppDelegate
 
-      @NSApplicationDelegateAdaptor private var appDelegate: MinimalMenuAppDelegate
-
-      var body: some Scene {
-        WindowGroup(vm!.name) {
-          Group {
-            VMView(vm: vm!).onAppear {
-              NSWindow.allowsAutomaticWindowTabbing = false
-            }.onDisappear {
-              let ret = kill(getpid(), MainApp.disappearSignal)
-              if ret != 0 {
-                // Fallback to the old termination method that doesn't
-                // propagate the cancellation to Task's in case graceful
-                // termination via kill(2) is not successful
-                NSApplication.shared.terminate(self)
-              }
-            }
-          }.frame(
-            minWidth: CGFloat(vm!.config.display.width),
-            idealWidth: CGFloat(vm!.config.display.width),
-            maxWidth: .infinity,
-            minHeight: CGFloat(vm!.config.display.height),
-            idealHeight: CGFloat(vm!.config.display.height),
-            maxHeight: .infinity
-          )
-        }.commands {
-          // Remove some standard menu options
-          CommandGroup(replacing: .help, addition: {})
-          CommandGroup(replacing: .newItem, addition: {})
-          CommandGroup(replacing: .pasteboard, addition: {})
-          CommandGroup(replacing: .textEditing, addition: {})
-          CommandGroup(replacing: .undoRedo, addition: {})
-          CommandGroup(replacing: .windowSize, addition: {})
-          // Replace some standard menu options
-          CommandGroup(replacing: .appInfo) { AboutTart(config: vm!.config) }
-          CommandMenu("Control") {
-            Button("Start") {
-              Task { try await vm!.virtualMachine.start() }
-            }
-            Button("Stop") {
-              Task { try await vm!.virtualMachine.stop() }
-            }
-            Button("Request Stop") {
-              Task { try vm!.virtualMachine.requestStop() }
-            }
-            if #available(macOS 14, *) {
-              Button("Suspend") {
-                kill(getpid(), SIGUSR1)
-              }
+  var body: some Scene {
+    WindowGroup(vm!.name) {
+      Group {
+        VMView(vm: vm!, capturesSystemKeys: MainApp.capturesSystemKeys).onAppear {
+          NSWindow.allowsAutomaticWindowTabbing = false
+        }.onDisappear {
+          let ret = kill(getpid(), MainApp.suspendable ? SIGUSR1 : SIGINT)
+          if ret != 0 {
+            // Fallback to the old termination method that doesn't
+            // propagate the cancellation to Task's in case graceful
+            // termination via kill(2) is not successful
+            NSApplication.shared.terminate(self)
+          }
+        }
+      }.frame(
+        minWidth: CGFloat(vm!.config.display.width),
+        idealWidth: CGFloat(vm!.config.display.width),
+        maxWidth: .infinity,
+        minHeight: CGFloat(vm!.config.display.height),
+        idealHeight: CGFloat(vm!.config.display.height),
+        maxHeight: .infinity
+      )
+    }.commands {
+      // Remove some standard menu options
+      CommandGroup(replacing: .help, addition: {})
+      CommandGroup(replacing: .newItem, addition: {})
+      CommandGroup(replacing: .pasteboard, addition: {})
+      CommandGroup(replacing: .textEditing, addition: {})
+      CommandGroup(replacing: .undoRedo, addition: {})
+      CommandGroup(replacing: .windowSize, addition: {})
+      // Replace some standard menu options
+      CommandGroup(replacing: .appInfo) { AboutTart(config: vm!.config) }
+      CommandMenu("Control") {
+        Button("Start") {
+          Task { try await vm!.virtualMachine.start() }
+        }
+        Button("Stop") {
+          Task { try await vm!.virtualMachine.stop() }
+        }
+        Button("Request Stop") {
+          Task { try vm!.virtualMachine.requestStop() }
+        }
+        if #available(macOS 14, *) {
+          if (MainApp.suspendable) {
+            Button("Suspend") {
+              kill(getpid(), SIGUSR1)
             }
           }
         }
       }
     }
-
-    MainApp.disappearSignal = suspendable ? SIGUSR1 : SIGINT
-    MainApp.main()
   }
 }
 
@@ -534,6 +677,18 @@ class MinimalMenuAppDelegate: NSObject, NSApplicationDelegate, ObservableObject
 
   func applicationDidFinishLaunching(_ : Notification) {
     NSApplication.shared.mainMenu?.removeItem(at: indexOfEditMenu)
+
+    let nsApp = NSApplication.shared
+    nsApp.setActivationPolicy(.regular)
+    nsApp.activate(ignoringOtherApps: true)
+  }
+
+  func applicationShouldTerminate(_ sender: NSApplication) -> NSApplication.TerminateReply {
+    if (kill(getpid(), MainApp.suspendable ? SIGUSR1 : SIGINT) == 0) {
+      return .terminateLater
+    } else {
+      return .terminateNow
+    }
   }
 }
 
@@ -573,18 +728,19 @@ struct VMView: NSViewRepresentable {
   typealias NSViewType = VZVirtualMachineView
 
   @ObservedObject var vm: VM
+  var capturesSystemKeys: Bool
 
   func makeNSView(context: Context) -> NSViewType {
     let machineView = VZVirtualMachineView()
 
-    // Do not capture system keys so that shortcuts like
-    // Shift-Command-4 + Space (capture a screenshot of window)
-    // work on the host instead of the guest
-    machineView.capturesSystemKeys = false
+    machineView.capturesSystemKeys = capturesSystemKeys
 
     // Enable automatic display reconfiguration
     // for guests that support it
-    if #available(macOS 14.0, *) {
+    //
+    // This is disabled for Linux because of poor HiDPI
+    // support, which manifests in fonts being too small
+    if #available(macOS 14.0, *), vm.config.os != .linux {
       machineView.automaticallyReconfiguresDisplay = true
     }
 
@@ -595,3 +751,152 @@ struct VMView: NSViewRepresentable {
     nsView.virtualMachine = vm.virtualMachine
   }
 }
+
+struct DirectoryShare {
+  let name: String?
+  let path: URL
+  let readOnly: Bool
+  let mountTag: String
+
+  init(parseFrom: String) throws {
+    var parseFrom = parseFrom
+
+    // Consume options
+    (self.readOnly, self.mountTag, parseFrom) = Self.parseOptions(parseFrom)
+
+    // Special case for URLs
+    if parseFrom.hasPrefix("http:") || parseFrom.hasPrefix("https:") {
+      self.name = nil
+      self.path = URL(string: parseFrom)!
+
+      return
+    }
+
+    let arguments = parseFrom.split(separator: ":", maxSplits: 1)
+
+    if arguments.count == 2 {
+      self.name = String(arguments[0])
+      self.path = String(arguments[1]).toRemoteOrLocalURL()
+    } else {
+      self.name = nil
+      self.path = String(arguments[0]).toRemoteOrLocalURL()
+    }
+  }
+
+  static func parseOptions(_ parseFrom: String) -> (Bool, String, String) {
+    var arguments = parseFrom.split(separator: ":")
+    let options = arguments.last!.split(separator: ",")
+
+    var readOnly: Bool = false
+    var mountTag: String = VZVirtioFileSystemDeviceConfiguration.macOSGuestAutomountTag
+
+    var found: Bool = false
+
+    for option in options {
+      switch true {
+      case option == "ro":
+        readOnly = true
+        found = true
+      case option.hasPrefix("tag="):
+        mountTag = String(option.dropFirst(4))
+        found = true
+      default:
+        continue
+      }
+    }
+
+    if found {
+      arguments.removeLast()
+    }
+
+    return (readOnly, mountTag, arguments.joined(separator: ":"))
+  }
+
+  func createConfiguration() throws -> VZSharedDirectory {
+    if (path.isFileURL) {
+      return VZSharedDirectory(url: path, readOnly: readOnly)
+    }
+
+    let urlCache = URLCache(memoryCapacity: 0, diskCapacity: 1 * 1024 * 1024 * 1024)
+
+    let archiveRequest = URLRequest(url: path, cachePolicy: .returnCacheDataElseLoad)
+    var response: CachedURLResponse? = urlCache.cachedResponse(for: archiveRequest)
+    if (response == nil || response?.data.isEmpty == true) {
+      print("Downloading \(path)...")
+      // download and unarchive remote directories if needed here
+      // use old school API to prevent deadlocks since we are running via MainActor
+      let downloadSemaphore = DispatchSemaphore(value: 0)
+      Task {
+        do {
+          let (archiveData, archiveResponse) = try await URLSession.shared.data(for: archiveRequest)
+          if archiveData.isEmpty {
+            print("Remote archive is empty!")
+          } else {
+            urlCache.storeCachedResponse(CachedURLResponse(response: archiveResponse, data: archiveData, storagePolicy: .allowed), for: archiveRequest)
+            print("Cached for future invocations!")
+          }
+        } catch {
+          print("Download failed: \(error)")
+        }
+        downloadSemaphore.signal()
+      }
+      downloadSemaphore.wait()
+      response = urlCache.cachedResponse(for: archiveRequest)
+    } else {
+      print("Using cached archive for \(path)...")
+    }
+
+    if (response == nil) {
+      throw ValidationError("Failed to fetch a remote archive!")
+    }
+
+    let temporaryLocation = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString + ".volume")
+    try FileManager.default.createDirectory(atPath: temporaryLocation.path, withIntermediateDirectories: true)
+    let lock = try FileLock(lockURL: temporaryLocation)
+    try lock.lock()
+
+    guard let executableURL = resolveBinaryPath("tar") else {
+      throw ValidationError("tar not found in PATH")
+    }
+
+    let process = Process.init()
+    process.executableURL = executableURL
+    process.currentDirectoryURL = temporaryLocation
+    process.arguments = ["-xz"]
+
+    let inPipe = Pipe()
+    process.standardInput = inPipe
+    process.launch()
+
+    inPipe.fileHandleForWriting.write(response!.data)
+    try inPipe.fileHandleForWriting.close()
+    process.waitUntilExit()
+
+    if !(process.terminationReason == .exit && process.terminationStatus == 0) {
+      throw ValidationError("Unarchiving failed!")
+    }
+
+    print("Unarchived into a temporary directory!")
+
+    return VZSharedDirectory(url: temporaryLocation, readOnly: readOnly)
+  }
+}
+
+extension String {
+  func toRemoteOrLocalURL() -> URL {
+    if (starts(with: "https://") || starts(with: "https://")) {
+      URL(string: self)!
+    } else {
+      URL(fileURLWithPath: NSString(string: self).expandingTildeInPath)
+    }
+  }
+}
+
+func pathHasMode(_ path: String, mode: mode_t) -> Bool {
+  var st = stat()
+  let statRes = stat(path, &st)
+  guard statRes != -1 else {
+    return false
+  }
+  return (st.st_mode & S_IFMT) == mode
+}

Sources/tart/Commands/Set.swift

@@ -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,29 @@ 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(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: """
+                             Disk resizing works on most cloud-ready Linux distributions out-of-the box (e.g. Ubuntu Cloud Images
+                             have the \"cloud-initramfs-growroot\" package installed that runs on boot) and on the rest of the
+                             distributions by running the \"growpart\" or \"resize2fs\" commands.
+
+                             For macOS, however, things are a bit more complicated: you need to remove the recovery partition
+                             first and then run various \"diskutil\" commands, see Tart's packer plugin source code for more
+                             details[1].
+
+                             [1]: https://github.com/cirruslabs/packer-plugin-tart/blob/main/builder/tart/step_disk_resize.go
+                             """))
   var diskSize: UInt16?
 
   func run() async throws {
@@ -40,8 +63,27 @@ struct Set: AsyncParsableCommand {
       }
     }
 
+    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!)
     }

Sources/tart/Commands/Stop.swift

@@ -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)
     }
   }
 
@@ -29,12 +29,12 @@ struct Stop: AsyncParsableCommand {
   }
 
   func stopRunning(_ vmDir: VMDirectory) async throws {
-    let lock = try PIDLock(lockURL: vmDir.configURL)
+    let lock = try vmDir.lock()
 
     // Find the VM's PID
     var pid = try lock.pid()
     if pid == 0 {
-      throw RuntimeError.VMNotRunning("VM \"\(name)\" is not running")
+      throw RuntimeError.VMNotRunning(name)
     }
 
     // Try to gracefully terminate the VM

Sources/tart/Commands/Suspend.swift

@@ -6,15 +6,15 @@ 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 {
     let vmDir = try VMStorageLocal().open(name)
-    let lock = try PIDLock(lockURL: vmDir.configURL)
+    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")
     }

Sources/tart/Credentials/DockerConfigCredentialsProvider.swift

@@ -11,7 +11,7 @@ class DockerConfigCredentialsProvider: CredentialsProvider {
     if let credentialsFromAuth = config.auths?[host]?.decodeCredentials() {
       return credentialsFromAuth
     }
-    if let helperProgram = config.credHelpers?[host] {
+    if let helperProgram = try config.findCredHelper(host: host) {
       return try executeHelper(binaryName: "docker-credential-\(helperProgram)", host: host)
     }
 
@@ -41,13 +41,18 @@ class DockerConfigCredentialsProvider: CredentialsProvider {
 
     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))
+      }
       throw CredentialsProviderError.Failed(message: "Docker helper failed!")
     }
+    if outputData == nil || outputData?.count == 0 {
+      throw CredentialsProviderError.Failed(message: "Docker helper output is empty!")
+    }
 
-    let getOutput = try JSONDecoder().decode(
-      DockerGetOutput.self, from: outPipe.fileHandleForReading.readDataToEndOfFile()
-    )
+    let getOutput = try JSONDecoder().decode(DockerGetOutput.self, from: outputData!)
     return (getOutput.Username, getOutput.Secret)
   }
 
@@ -59,6 +64,26 @@ class DockerConfigCredentialsProvider: CredentialsProvider {
 struct DockerConfig: Codable {
   var auths: Dictionary<String, DockerAuthConfig>? = Dictionary()
   var credHelpers: Dictionary<String, String>? = Dictionary()
+
+  func findCredHelper(host: String) throws -> String? {
+    // Tart supports wildcards in credHelpers
+    // Similar to what is requested from Docker: https://github.com/docker/cli/issues/2928
+
+    guard let credHelpers else {
+      return nil
+    }
+
+    for (hostPattern, helperProgram) in credHelpers {
+      if (hostPattern == host) {
+        return helperProgram
+      }
+      let compiledPattern = try? Regex(hostPattern)
+      if (try compiledPattern?.wholeMatch(in: host) != nil) {
+        return helperProgram
+      }
+    }
+    return nil
+  }
 }
 
 struct DockerAuthConfig: Codable {

Sources/tart/Credentials/KeychainCredentialsProvider.swift

@@ -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)
@@ -61,6 +61,24 @@ class KeychainCredentialsProvider: CredentialsProvider {
       throw CredentialsProviderError.Failed(message: "Keychain failed to find item: \(status.explanation())")
     }
   }
+
+  func remove(host: String) throws {
+    let query: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
+                                kSecAttrServer as String: host,
+                                kSecAttrLabel as String: "Tart Credentials",
+    ]
+
+    let status = SecItemDelete(query as CFDictionary)
+
+    switch status {
+    case errSecSuccess:
+      return
+    case errSecItemNotFound:
+      return
+    default:
+      throw CredentialsProviderError.Failed(message: "Failed to remove Keychain item(s): \(status.explanation())")
+    }
+  }
 }
 
 extension OSStatus {

Sources/tart/Credentials/StdinCredentials.swift

@@ -13,7 +13,7 @@ class StdinCredentials {
     return (user, password)
   }
 
-  private static func readStdinCredential(name: String, prompt: String, maxCharacters: Int = 255, isSensitive: Bool) throws -> String {
+  private static func readStdinCredential(name: String, prompt: String, maxCharacters: Int = 1024, isSensitive: Bool) throws -> String {
     var buf = [CChar](repeating: 0, count: maxCharacters + 1 /* sentinel */ + 1 /* NUL */)
     guard let rawCredential = readpassphrase(prompt, &buf, buf.count, isSensitive ? RPP_ECHO_OFF : RPP_ECHO_ON) else {
       throw StdinCredentialsError.CredentialRequired(which: name)

Sources/tart/Fetcher.swift

@@ -3,19 +3,32 @@ 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)
+class DownloadDelegate: NSObject, URLSessionTaskDelegate {
+  let progress: Progress
+  init(_ progress: Progress) throws {
+    self.progress = progress
   }
 
-  private static func fetchViaMemory(_ request: URLRequest) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  func urlSession(_ session: URLSession, didCreateTask task: URLSessionTask) {
+    self.progress.addChild(task.progress, withPendingUnitCount: self.progress.totalUnitCount)
+  }
+}
+
+class Fetcher {
+  static func fetch(_ request: URLRequest, viaFile: Bool = false, progress: Progress? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+    let delegate = progress != nil ? try DownloadDelegate(progress!) : nil
+
+    if viaFile {
+      return try await fetchViaFile(request, delegate: delegate)
+    }
+
+    return try await fetchViaMemory(request, delegate: delegate)
+  }
+
+  private static func fetchViaMemory(_ request: URLRequest, delegate: URLSessionTaskDelegate? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
     let dataCh = AsyncThrowingChannel<Data, Error>()
 
-    let (data, response) = try await urlSession.data(for: request)
+    let (data, response) = try await urlSession.data(for: request, delegate: delegate)
 
     Task {
       await dataCh.send(data)
@@ -26,21 +39,21 @@ class Fetcher {
     return (dataCh, response as! HTTPURLResponse)
   }
 
-  private static func fetchViaFile(_ request: URLRequest) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
+  private static func fetchViaFile(_ request: URLRequest, delegate: URLSessionTaskDelegate? = nil) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
     let dataCh = AsyncThrowingChannel<Data, Error>()
 
-    let (fileURL, response) = try await urlSession.download(for: request)
+    let (fileURL, response) = try await urlSession.download(for: request, delegate: delegate)
 
     // 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 fh = try FileHandle(forReadingFrom: fileURL)
+    let mappedFile = try Data(contentsOf: fileURL, options: [.alwaysMapped])
     try FileManager.default.removeItem(at: fileURL)
 
     Task {
-      while let data = try fh.read(upToCount: 64 * 1024 * 1024) {
-        await dataCh.send(data)
+      for chunk in (0 ..< mappedFile.count).chunks(ofCount: 64 * 1024 * 1024) {
+        await dataCh.send(mappedFile.subdata(in: chunk))
       }
 
       dataCh.finish()

Sources/tart/LocalLayerCache.swift

@@ -0,0 +1,32 @@
+import Foundation
+
+struct LocalLayerCache {
+  private let mappedDisk: Data
+  private var digestToRange: [String : Range<Data.Index>] = [:]
+
+  init?(_ diskURL: URL, _ manifest: OCIManifest) throws {
+    // 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
+      }
+
+      self.digestToRange[layer.digest] = Int(offset)..<Int(offset+uncompressedSize)
+
+      offset += uncompressedSize
+    }
+  }
+
+  func find(_ digest: String) -> Data? {
+    guard let foundRange = self.digestToRange[digest] else {
+      return nil
+    }
+
+    return self.mappedDisk.subdata(in: foundRange)
+  }
+}

Sources/tart/MACAddressResolver/Lease.swift

@@ -1,13 +1,17 @@
+import Foundation
 import Network
+import SwiftRadix
 
 struct Lease {
   var mac: MACAddress
   var ip: IPv4Address
+  var expiresAt: Date
 
   init?(fromRawLease: [String : String]) {
     // Retrieve the required fields
     guard let hwAddress = fromRawLease["hw_address"] else { return nil }
     guard let ipAddress = fromRawLease["ip_address"] else { return nil }
+    guard let lease = fromRawLease["lease"] else { return nil }
 
     // Parse MAC address
     let hwAddressSplits = hwAddress.split(separator: ",")
@@ -26,7 +30,13 @@ struct Lease {
       return nil
     }
 
+    // Parse expiration timestamp
+    guard let leaseTimestamp = lease.hex?.value else {
+      return nil
+    }
+
     self.ip = ip
     self.mac = mac
+    self.expiresAt = Date(timeIntervalSince1970: TimeInterval(leaseTimestamp))
   }
 }

Sources/tart/MACAddressResolver/Leases.swift

@@ -37,13 +37,18 @@ class Leases {
   }
 
   init(_ fromString: String) throws {
-    var leases: [MACAddress : Lease] = Dictionary()
+    let leases = try Self.retrieveRawLeases(fromString).compactMap({ rawLease in
+      Lease(fromRawLease: rawLease)
+    }).filter({ lease in
+      lease.expiresAt.isInFuture
+    }).map({ lease in
+      (lease.mac, lease)
+    })
 
-    for lease in try Self.retrieveRawLeases(fromString).compactMap({ Lease(fromRawLease: $0) }) {
-      leases[lease.mac] = lease
+    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
     }
-
-    self.leases = leases
   }
 
   /// Parse leases from the host cache similarly to the PLCache_read() function found in Apple's Open Source releases.
@@ -107,7 +112,7 @@ class Leases {
     return rawLeases
   }
 
-  func ResolveMACAddress(macAddress: MACAddress) throws -> IPv4Address? {
+  func ResolveMACAddress(macAddress: MACAddress) -> IPv4Address? {
     leases[macAddress]?.ip
   }
 }

Sources/tart/Network/Network.swift

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

Sources/tart/Network/NetworkBridged.swift

@@ -1,18 +1,19 @@
 import Foundation
+import Semaphore
 import Virtualization
 
 class NetworkBridged: Network {
-  let interface: VZBridgedNetworkInterface
+  let interfaces: [VZBridgedNetworkInterface]
 
-  init(interface: VZBridgedNetworkInterface) {
-    self.interface = interface
+  init(interfaces: [VZBridgedNetworkInterface]) {
+    self.interfaces = interfaces
   }
 
-  func attachment() -> VZNetworkDeviceAttachment {
-    VZBridgedNetworkDeviceAttachment(interface: interface)
+  func attachments() -> [VZNetworkDeviceAttachment] {
+    interfaces.map { VZBridgedNetworkDeviceAttachment(interface: $0) }
   }
 
-  func run(_ sema: DispatchSemaphore) throws {
+  func run(_ sema: AsyncSemaphore) throws {
     // no-op, only used for Softnet
   }
 

Sources/tart/Network/NetworkShared.swift

@@ -1,12 +1,13 @@
 import Foundation
+import Semaphore
 import Virtualization
 
 class NetworkShared: Network {
-  func attachment() -> VZNetworkDeviceAttachment {
-    VZNATNetworkDeviceAttachment()
+  func attachments() -> [VZNetworkDeviceAttachment] {
+    [VZNATNetworkDeviceAttachment()]
   }
 
-  func run(_ sema: DispatchSemaphore) throws {
+  func run(_ sema: AsyncSemaphore) throws {
     // no-op, only used for Softnet
   }
 

Sources/tart/Network/Softnet.swift

@@ -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 {
@@ -92,9 +93,9 @@ class Softnet: Network {
     }
   }
 
-  func attachment() -> VZNetworkDeviceAttachment {
+  func attachments() -> [VZNetworkDeviceAttachment] {
     let fh = FileHandle.init(fileDescriptor: vmFD)
-    return VZFileHandleNetworkDeviceAttachment(fileHandle: fh)
+    return [VZFileHandleNetworkDeviceAttachment(fileHandle: fh)]
   }
 
   static func configureSUIDBitIfNeeded() throws {

Sources/tart/OCI/AuthenticationKeeper.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+actor AuthenticationKeeper {
+  var authentication: Authentication? = nil
+
+  func set(_ authentication: Authentication) {
+    self.authentication = authentication
+  }
+
+  func header() -> (String, String)? {
+    if let authentication = authentication {
+      // Do not suggest any headers if the
+      // authentication token has expired
+      if !authentication.isValid() {
+        return nil
+      }
+
+      return authentication.header()
+    }
+
+    // Do not suggest any headers if the
+    // authentication token is not set
+    return nil
+  }
+}

Sources/tart/OCI/Digest.swift

@@ -1,6 +1,11 @@
 import Foundation
 import CryptoKit
 
+enum DigestError: Error {
+  case InvalidOffset
+  case InvalidSize
+}
+
 class Digest {
   var hash: SHA256 = SHA256()
 
@@ -15,6 +20,37 @@ class Digest {
   static func hash(_ data: Data) -> String {
     SHA256.hash(data: data).hexdigest()
   }
+
+  static func hash(_ url: URL) throws -> String {
+    hash(try Data(contentsOf: url))
+  }
+
+  static func hash(_ url: URL, offset: UInt64, size: UInt64) throws -> String {
+    // Sanity check
+    let fhSanity = try FileHandle(forReadingFrom: url)
+    try fhSanity.seekToEnd()
+    let fileSize = try fhSanity.offset()
+    try fhSanity.close()
+
+    if offset > fileSize {
+      throw DigestError.InvalidOffset
+    }
+
+    if (offset + size) > fileSize {
+      throw DigestError.InvalidSize
+    }
+
+    // Read a chunk of size ``size`` at offset ``offset``
+    // and calculate it's digest
+    let fh = try FileHandle(forReadingFrom: url)
+    defer { try! fh.close() }
+
+    try fh.seek(toOffset: offset)
+
+    let data = try fh.read(upToCount: Int(size))!
+
+    return hash(data)
+  }
 }
 
 extension SHA256.Digest {

Sources/tart/OCI/Layerizer/Disk.swift

@@ -0,0 +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, localLayerCache: LocalLayerCache?) async throws
+}

Sources/tart/OCI/Layerizer/DiskV1.swift

@@ -0,0 +1,75 @@
+import Foundation
+import Compression
+
+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] {
+    var pushedLayers: [OCIManifestLayer] = []
+
+    // Open the disk file
+    let mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
+    var mappedDiskReadOffset = 0
+
+    // Compress the disk file as a single stream
+    let compressingFilter = try InputFilter(.compress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { (length: Int) -> Data? in
+      // Determine the size of the next chunk
+      let bytesRead = min(length, mappedDisk.count - mappedDiskReadOffset)
+
+      // Read the next uncompressed chunk
+      let data = mappedDisk.subdata(in: mappedDiskReadOffset ..< mappedDiskReadOffset + bytesRead)
+
+      // Advance the offset
+      mappedDiskReadOffset += bytesRead
+
+      // Provide the uncompressed chunk to the compressing filter
+      return data
+    }
+
+    // Cut the compressed stream into layers, each equal exactly ``Self.layerLimitBytes`` bytes,
+    // except for the last one, which may be smaller
+    while let compressedData = try compressingFilter.readData(ofLength: Self.layerLimitBytes) {
+      let layerDigest = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb)
+
+      pushedLayers.append(OCIManifestLayer(
+        mediaType: diskV1MediaType,
+        size: compressedData.count,
+        digest: layerDigest
+      ))
+
+      // Update progress using an absolute value
+      progress.completedUnitCount = Int64(mappedDiskReadOffset)
+    }
+
+    return pushedLayers
+  }
+
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil) async throws {
+    if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
+      throw OCIError.FailedToCreateVmFile
+    }
+
+    // Open the disk file
+    let disk = try FileHandle(forWritingTo: diskURL)
+    defer { try! disk.close() }
+
+    // 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)
+      }
+    }
+
+    for diskLayer in diskLayers {
+      try await registry.pullBlob(diskLayer.digest) { data in
+        try filter.write(data)
+
+        // Update the progress
+        progress.completedUnitCount += Int64(data.count)
+      }
+    }
+
+    try filter.finalize()
+  }
+}

Sources/tart/OCI/Layerizer/DiskV2.swift

@@ -0,0 +1,166 @@
+import Foundation
+import Compression
+
+class DiskV2: Disk {
+  private static let bufferSizeBytes = 4 * 1024 * 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] = []
+
+    // Open the disk file
+    let mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
+
+    // Compress the disk file as multiple individually decompressible streams,
+    // each equal ``Self.layerLimitBytes`` bytes or less due to LZ4 compression
+    for data in mappedDisk.chunks(ofCount: layerLimitBytes) {
+      let compressedData = try (data as NSData).compressed(using: .lz4) as Data
+
+      let layerDigest = try await registry.pushBlob(fromData: compressedData, chunkSizeMb: chunkSizeMb)
+
+      pushedLayers.append(OCIManifestLayer(
+        mediaType: diskV2MediaType,
+        size: compressedData.count,
+        digest: layerDigest,
+        uncompressedSize: UInt64(data.count),
+        uncompressedContentDigest: Digest.hash(data)
+      ))
+
+      // Update progress using a relative value
+      progress.completedUnitCount += Int64(data.count)
+    }
+
+    return pushedLayers
+  }
+
+  static func pull(registry: Registry, diskLayers: [OCIManifestLayer], diskURL: URL, concurrency: UInt, progress: Progress, localLayerCache: LocalLayerCache? = nil) 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
+    }
+
+    // Calculate the uncompressed disk size
+    var uncompressedDiskSize: UInt64 = 0
+
+    for layer in diskLayers {
+      guard let uncompressedLayerSize = layer.uncompressedSize() else {
+        throw OCIError.LayerIsMissingUncompressedSizeAnnotation
+      }
+
+      uncompressedDiskSize += uncompressedLayerSize
+    }
+
+    // Truncate the target disk file so that it will be able
+    // to accomodate the uncompressed disk size
+    let disk = try FileHandle(forWritingTo: diskURL)
+    try disk.truncate(atOffset: uncompressedDiskSize)
+    try disk.close()
+
+    // Concurrently fetch and decompress layers
+    try await withThrowingTaskGroup(of: Void.self) { group in
+      var globalDiskWritingOffset: UInt64 = 0
+
+      for (index, diskLayer) in diskLayers.enumerated() {
+        // Respect the concurrency limit
+        if index >= concurrency {
+          try await group.next()
+        }
+
+        // Retrieve layer annotations
+        guard let uncompressedLayerSize = diskLayer.uncompressedSize() else {
+          throw OCIError.LayerIsMissingUncompressedSizeAnnotation
+        }
+        guard let uncompressedLayerContentDigest = diskLayer.uncompressedContentDigest() else {
+          throw OCIError.LayerIsMissingUncompressedDigestAnnotation
+        }
+
+        // Capture the current disk writing offset
+        let diskWritingOffset = globalDiskWritingOffset
+
+        // 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 {
+            // Update the progress
+            progress.completedUnitCount += Int64(diskLayer.size)
+
+            return
+          }
+
+          // Open the disk file
+          let disk = try FileHandle(forWritingTo: diskURL)
+
+          // Check if we already have this layer contents in the local layer cache
+          if let localLayerCache = localLayerCache, let data = localLayerCache.find(diskLayer.digest), Digest.hash(data) == uncompressedLayerContentDigest {
+            // Fulfil the layer contents from the local blob cache
+            _ = try zeroSkippingWrite(disk, diskWritingOffset, data)
+            try disk.close()
+
+            // Update the progress
+            progress.completedUnitCount += Int64(diskLayer.size)
+
+            return
+          }
+
+          var diskWritingOffset = diskWritingOffset
+
+          // Pull and decompress a single layer into the specific offset on disk
+          let filter = try OutputFilter(.decompress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { data in
+            guard let data = data else {
+              return
+            }
+
+            diskWritingOffset = try zeroSkippingWrite(disk, diskWritingOffset, data)
+          }
+
+          try await registry.pullBlob(diskLayer.digest) { data in
+            try filter.write(data)
+
+            // Update the progress
+            progress.completedUnitCount += Int64(data.count)
+          }
+
+          try filter.finalize()
+
+          try disk.close()
+        }
+
+        globalDiskWritingOffset += uncompressedLayerSize
+      }
+    }
+  }
+
+  private static func zeroSkippingWrite(_ disk: FileHandle, _ offset: UInt64, _ data: Data) throws -> UInt64 {
+    let holeGranularityBytes = 64 * 1024
+
+    // 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 offset = offset
+
+    for chunk in data.chunks(ofCount: holeGranularityBytes) {
+      // Only write chunks that are not zero
+      if chunk != zeroChunk {
+        try disk.seek(toOffset: offset)
+        disk.write(chunk)
+      }
+
+      offset += UInt64(chunk.count)
+    }
+
+    return offset
+  }
+}

Sources/tart/OCI/Manifest.swift

@@ -1,10 +1,22 @@
 import Foundation
 
+// OCI manifest and OCI config media types
 let ociManifestMediaType = "application/vnd.oci.image.manifest.v1+json"
 let ociConfigMediaType = "application/vnd.oci.image.config.v1+json"
 
-// Annotations
+// Layer media types
+let configMediaType = "application/vnd.cirruslabs.tart.config.v1"
+let diskV1MediaType = "application/vnd.cirruslabs.tart.disk.v1"
+let diskV2MediaType = "application/vnd.cirruslabs.tart.disk.v2"
+let nvramMediaType = "application/vnd.cirruslabs.tart.nvram.v1"
+
+// Manifest annotations
 let uncompressedDiskSizeAnnotation = "org.cirruslabs.tart.uncompressed-disk-size"
+let uploadTimeAnnotation = "org.cirruslabs.tart.upload-time"
+
+// Layer annotations
+let uncompressedSizeAnnotation = "org.cirruslabs.tart.uncompressed-size"
+let uncompressedContentDigestAnnotation = "org.cirruslabs.tart.uncompressed-content-digest"
 
 struct OCIManifest: Codable, Equatable {
   var schemaVersion: Int = 2
@@ -13,15 +25,21 @@ struct OCIManifest: Codable, Equatable {
   var layers: [OCIManifestLayer] = Array()
   var annotations: Dictionary<String, String>?
 
-  init(config: OCIManifestConfig, layers: [OCIManifestLayer], uncompressedDiskSize: UInt64? = nil) {
+  init(config: OCIManifestConfig, layers: [OCIManifestLayer], uncompressedDiskSize: UInt64? = nil, uploadDate: Date? = nil) {
     self.config = config
     self.layers = layers
 
+    var annotations: [String: String] = [:]
+
     if let uncompressedDiskSize = uncompressedDiskSize {
-      annotations = [
-        uncompressedDiskSizeAnnotation: String(uncompressedDiskSize)
-      ]
+      annotations[uncompressedDiskSizeAnnotation] = String(uncompressedDiskSize)
     }
+
+    if let uploadDate = uploadDate {
+      annotations[uploadTimeAnnotation] = uploadDate.toISO()
+    }
+
+    self.annotations = annotations
   }
 
   init(fromJSON: Data) throws {
@@ -60,10 +78,49 @@ 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
+  var annotations: Dictionary<String, String>?
+
+  init(mediaType: String, size: Int, digest: String, uncompressedSize: UInt64? = nil, uncompressedContentDigest: String? = nil) {
+    self.mediaType = mediaType
+    self.size = size
+    self.digest = digest
+
+    var annotations: [String: String] = [:]
+
+    if let uncompressedSize = uncompressedSize {
+      annotations[uncompressedSizeAnnotation] = String(uncompressedSize)
+    }
+
+    if let uncompressedContentDigest = uncompressedContentDigest {
+      annotations[uncompressedContentDigestAnnotation] = uncompressedContentDigest
+    }
+
+    self.annotations = annotations
+  }
+
+  func uncompressedSize() -> UInt64? {
+    guard let value = annotations?[uncompressedSizeAnnotation] else {
+      return nil
+    }
+
+    return UInt64(value)
+  }
+
+  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 {

Sources/tart/OCI/Registry.swift

@@ -42,9 +42,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 +63,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 +83,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)
     }
   }
 
@@ -102,8 +100,7 @@ class Registry {
   private let baseURL: URL
   let namespace: String
   let credentialsProviders: [CredentialsProvider]
-
-  var currentAuthToken: Authentication? = nil
+  let authenticationKeeper = AuthenticationKeeper()
 
   var host: String? {
     guard let host = baseURL.host else { return nil }
@@ -115,11 +112,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
   }
@@ -133,7 +130,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 {
@@ -242,7 +249,7 @@ class Registry {
     return digest
   }
 
-  public func pullBlob(_ digest: String, handler: (Data) throws -> Void) async throws {
+  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()
@@ -253,7 +260,7 @@ class Registry {
     for try await part in channel {
       try Task.checkCancellation()
 
-      try handler(Data(part))
+      try await handler(part)
     }
   }
 
@@ -305,11 +312,6 @@ class Registry {
       request.httpBody = body
     }
 
-    // Invalidate token if it has expired
-    if currentAuthToken?.isValid() == false {
-      currentAuthToken = nil
-    }
-
     var (channel, response) = try await authAwareRequest(request: request, viaFile: viaFile)
 
     if doAuth && response.statusCode == HTTPCode.Unauthorized.rawValue {
@@ -331,7 +333,7 @@ class Registry {
 
     if wwwAuthenticate.scheme.lowercased() == "basic" {
       if let (user, password) = try lookupCredentials() {
-        currentAuthToken = BasicAuthentication(user: user, password: password)
+        await authenticationKeeper.set(BasicAuthentication(user: user, password: password))
       }
 
       return
@@ -378,7 +380,7 @@ class Registry {
         + "while retrieving an authentication token", details: data.asText())
     }
 
-    currentAuthToken = try TokenResponse.parse(fromData: data)
+    await authenticationKeeper.set(try TokenResponse.parse(fromData: data))
   }
 
   private func lookupCredentials() throws -> (String, String)? {
@@ -399,8 +401,7 @@ class Registry {
   private func authAwareRequest(request: URLRequest, viaFile: Bool = false) async throws -> (AsyncThrowingChannel<Data, Error>, HTTPURLResponse) {
     var request = request
 
-    if let token = currentAuthToken {
-      let (name, value) = token.header()
+    if let (name, value) = await authenticationKeeper.header() {
       request.addValue(value, forHTTPHeaderField: name)
     }
 

Sources/tart/Platform/Darwin.swift

@@ -6,129 +6,117 @@ 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: Platform {
+    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(contentsOf: 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 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()
+      }
+
+      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 [VZMacKeyboardConfiguration()]
+      } else {
+        return [VZUSBKeyboardConfiguration()]
+      }
+    }
 
-    return result
-  }
-
-  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] {
+      if #available(macOS 13, *) {
+        return [VZMacTrackpadConfiguration()]
+      } else {
+        // fallback to the regular configuration
+        return [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+      }
     }
   }
 
-  func keyboardsSuspendable() -> [VZKeyboardConfiguration] {
-    if #available(macOS 14, *) {
-      return [VZMacKeyboardConfiguration()]
-    } else {
-      return []
-    }
-  }
-
-  func pointingDevices() -> [VZPointingDeviceConfiguration] {
-    if #available(macOS 13, *) {
-      // Trackpad is only supported by guests starting with macOS Ventura
-      return [VZMacTrackpadConfiguration(), VZUSBScreenCoordinatePointingDeviceConfiguration()]
-    } else {
-      return [VZUSBScreenCoordinatePointingDeviceConfiguration()]
-    }
-  }
-
-  func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration] {
-    if #available(macOS 13, *) {
-      return [VZMacTrackpadConfiguration()]
-    } else {
-      return []
-    }
-  }
-}
+#endif

Sources/tart/Platform/Platform.swift

@@ -8,8 +8,3 @@ protocol Platform: Codable {
   func keyboards() -> [VZKeyboardConfiguration]
   func pointingDevices() -> [VZPointingDeviceConfiguration]
 }
-
-protocol PlatformSuspendable: Platform {
-  func pointingDevicesSuspendable() -> [VZPointingDeviceConfiguration]
-  func keyboardsSuspendable() -> [VZKeyboardConfiguration]
-}

Sources/tart/Prunable.swift

@@ -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
 }

Sources/tart/Root.swift

@@ -16,6 +16,7 @@ struct Root: AsyncParsableCommand {
       Get.self,
       List.self,
       Login.self,
+      Logout.self,
       IP.self,
       Pull.self,
       Push.self,
@@ -25,6 +26,7 @@ struct Root: AsyncParsableCommand {
       Rename.self,
       Stop.self,
       Delete.self,
+      FQN.self,
     ])
 
   public static func main() async throws {
@@ -48,6 +50,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
@@ -81,10 +87,12 @@ struct Root: AsyncParsableCommand {
       var command = try parseAsRoot()
 
       // Run garbage-collection before each command (shouldn't take too long)
-      do {
-        try Config().gc()
-      } catch {
-        fputs("Failed to perform garbage collection!\n\(error)\n", stderr)
+      if type(of: command) != type(of: Pull()) && type(of: command) != type(of: Clone()){
+        do {
+          try Config().gc()
+        } catch {
+          fputs("Failed to perform garbage collection!\n\(error)\n", stderr)
+        }
       }
 
       if var asyncCommand = command as? AsyncParsableCommand {

Sources/tart/ShellCompletions/ShellCompletions.swift

@@ -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) }
+}

Sources/tart/URL+Prunable.swift

@@ -9,7 +9,11 @@ extension URL: Prunable {
     try FileManager.default.removeItem(at: self)
   }
 
-  func sizeBytes() throws -> Int {
+  func allocatedSizeBytes() throws -> Int {
     try resourceValues(forKeys: [.totalFileAllocatedSizeKey]).totalFileAllocatedSize!
   }
+
+  func sizeBytes() throws -> Int {
+    try resourceValues(forKeys: [.totalFileSizeKey]).totalFileSize!
+  }
 }

Sources/tart/VM.swift

@@ -1,6 +1,7 @@
 import Foundation
 import Virtualization
 import AsyncAlgorithms
+import Semaphore
 
 struct UnsupportedRestoreImageError: Error {
 }
@@ -30,7 +31,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
@@ -42,10 +43,12 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
   init(vmDir: VMDirectory,
        network: Network = NetworkShared(),
-       additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = [],
+       additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
        directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
        serialPorts: [VZSerialPortConfiguration] = [],
-       suspendable: Bool = false
+       suspendable: Bool = false,
+       audio: Bool = true,
+       clipboard: Bool = true
   ) throws {
     name = vmDir.name
     config = try VMConfig.init(fromURL: vmDir.configURL)
@@ -58,10 +61,12 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     self.network = network
     configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL,
                                                 nvramURL: vmDir.nvramURL, vmConfig: config,
-                                                network: network, additionalDiskAttachments: additionalDiskAttachments,
+                                                network: network, additionalStorageDevices: additionalStorageDevices,
                                                 directorySharingDevices: directorySharingDevices,
                                                 serialPorts: serialPorts,
-                                                suspendable: suspendable
+                                                suspendable: suspendable,
+                                                audio: audio,
+                                                clipboard: clipboard
     )
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
@@ -71,9 +76,11 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
   static func retrieveIPSW(remoteURL: URL) async throws -> URL {
     // Check if we already have this IPSW in cache
-    let (channel, response) = try await Fetcher.fetch(URLRequest(url: remoteURL), viaFile: true)
+    var headRequest = URLRequest(url: remoteURL)
+    headRequest.httpMethod = "HEAD"
+    let (_, headResponse) = try await Fetcher.fetch(headRequest, viaFile: false)
 
-    if let hash = response.value(forHTTPHeaderField: "x-amz-meta-digest-sha256") {
+    if let hash = headResponse.value(forHTTPHeaderField: "x-amz-meta-digest-sha256") {
       let ipswLocation = try IPSWCache().locationFor(fileName: "sha256:\(hash).ipsw")
 
       if FileManager.default.fileExists(atPath: ipswLocation.path) {
@@ -87,10 +94,17 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     // Download the IPSW
     defaultLogger.appendNewLine("Fetching \(remoteURL.lastPathComponent)...")
 
-    let progress = Progress(totalUnitCount: response.expectedContentLength)
-    ProgressObserver(progress).log(defaultLogger)
+    let downloadProgress = Progress(totalUnitCount: 100)
+    ProgressObserver(downloadProgress).log(defaultLogger)
+
+    let request = URLRequest(url: remoteURL)
+    let (channel, response) = try await Fetcher.fetch(request, viaFile: true, progress: downloadProgress)
 
     let temporaryLocation = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString + ".ipsw")
+    defaultLogger.appendNewLine("Computing digest for \(temporaryLocation.path)...")
+    let digestProgress = Progress(totalUnitCount: response.expectedContentLength)
+    ProgressObserver(digestProgress).log(defaultLogger)
+
     FileManager.default.createFile(atPath: temporaryLocation.path, contents: nil)
     let lock = try FileLock(lockURL: temporaryLocation)
     try lock.lock()
@@ -102,7 +116,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       let chunkAsData = Data(chunk)
       fileHandle.write(chunkAsData)
       digest.update(chunkAsData)
-      progress.completedUnitCount += Int64(chunk.count)
+      digestProgress.completedUnitCount += Int64(chunk.count)
     }
 
     try fileHandle.close()
@@ -112,18 +126,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 ||
@@ -133,82 +135,90 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
   }
 
-  init(
-    vmDir: VMDirectory,
-    ipswURL: URL,
-    diskSizeGB: UInt16,
-    network: Network = NetworkShared(),
-    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = [],
-    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,
-                                                additionalDiskAttachments: additionalDiskAttachments,
-                                                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 {
@@ -225,7 +235,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     return try VM(vmDir: vmDir)
   }
 
-  func run(recovery: Bool, resume shouldResume: Bool) async throws {
+  func start(recovery: Bool, resume shouldResume: Bool) async throws {
     try network.run(sema)
 
     if shouldResume {
@@ -233,17 +243,21 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     } else {
       try await start(recovery)
     }
+  }
 
-    await withTaskCancellationHandler(operation: {
-      // Wait for the VM to finish running
-      // or for the exit condition
-      sema.wait()
-    }, onCancel: {
-      sema.signal()
-    })
+  func run() async throws {
+    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()
@@ -251,15 +265,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
 
   @MainActor
   private func start(_ recovery: Bool) async throws {
-    if #available(macOS 13, *) {
-      // new API introduced in Ventura
+    #if arch(arm64)
       let startOptions = VZMacOSVirtualMachineStartOptions()
       startOptions.startUpFromMacOSRecovery = recovery
       try await virtualMachine.start(options: startOptions)
-    } else {
-      // use method that also available on Monterey
-      try await virtualMachine.start(recovery)
-    }
+    #else
+      try await virtualMachine.start()
+    #endif
   }
 
   @MainActor
@@ -277,10 +289,12 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     nvramURL: URL,
     vmConfig: VMConfig,
     network: Network = NetworkShared(),
-    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment],
+    additionalStorageDevices: [VZStorageDeviceConfiguration],
     directorySharingDevices: [VZDirectorySharingDeviceConfiguration],
     serialPorts: [VZSerialPortConfiguration],
-    suspendable: Bool = false
+    suspendable: Bool = false,
+    audio: Bool = true,
+    clipboard: Bool = true
   ) throws -> VZVirtualMachineConfiguration {
     let configuration = VZVirtualMachineConfiguration()
 
@@ -298,7 +312,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     configuration.graphicsDevices = [vmConfig.platform.graphicsDevice(vmConfig: vmConfig)]
 
     // Audio
-    if !suspendable {
+    if audio && !suspendable {
       let soundDeviceConfiguration = VZVirtioSoundDeviceConfiguration()
       let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
       inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
@@ -309,24 +323,42 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     // 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()
-    }
+    configuration.keyboards = vmConfig.platform.keyboards()
+    configuration.pointingDevices = vmConfig.platform.pointingDevices()
 
     // Networking
-    let vio = VZVirtioNetworkDeviceConfiguration()
-    vio.attachment = network.attachment()
-    vio.macAddress = vmConfig.macAddress
-    configuration.networkDevices = [vio]
+    configuration.networkDevices = network.attachments().map {
+      let vio = VZVirtioNetworkDeviceConfiguration()
+      vio.attachment = $0
+      vio.macAddress = vmConfig.macAddress
+      return vio
+    }
+
+    // Clipboard sharing via Spice agent
+    if clipboard && vmConfig.os == .linux {
+      let spiceAgentConsoleDevice = VZVirtioConsoleDeviceConfiguration()
+      let spiceAgentPort = VZVirtioConsolePortConfiguration()
+      spiceAgentPort.name = VZSpiceAgentPortAttachment.spiceAgentPortName
+      spiceAgentPort.attachment = VZSpiceAgentPortAttachment()
+      spiceAgentConsoleDevice.ports[0] = spiceAgentPort
+      configuration.consoleDevices.append(spiceAgentConsoleDevice)
+    }
 
     // Storage
-    var attachments = [try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)]
-    attachments.append(contentsOf: additionalDiskAttachments)
-    configuration.storageDevices = attachments.map { VZVirtioBlockDeviceConfiguration(attachment: $0) }
+    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)
+    }
+    var devices: [VZStorageDeviceConfiguration] = [device]
+    devices.append(contentsOf: additionalStorageDevices)
+    configuration.storageDevices = devices
 
     // Entropy
     if !suspendable {
@@ -343,7 +375,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     //
     // A dummy console device useful for implementing
     // host feature checks in the guest agent software.
-    if #available(macOS 13, *) {
+    if !suspendable {
       let consolePort = VZVirtioConsolePortConfiguration()
       consolePort.name = "tart-version-\(CI.version)"
 

Sources/tart/VMConfig.swift

@@ -95,13 +95,16 @@ 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:
-      if #available(macOS 13, *) {
-        platform = try Linux(from: decoder)
-      } else {
-        throw UnsupportedOSError("Linux VMs", "are")
-      }
+      platform = try Linux(from: decoder)
     }
     cpuCountMin = try container.decode(Int.self, forKey: .cpuCountMin)
     cpuCount = try container.decode(Int.self, forKey: .cpuCount)
@@ -136,20 +139,30 @@ struct VMConfig: Codable {
   }
 
   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
   }
 }

Sources/tart/VMDirectory+OCI.swift

@@ -1,33 +1,23 @@
-import Foundation
 import Compression
+import Foundation
 import Sentry
 
 enum OCIError: Error {
   case ShouldBeExactlyOneLayer
   case ShouldBeAtLeastOneLayer
   case FailedToCreateVmFile
+  case LayerIsMissingUncompressedSizeAnnotation
+  case LayerIsMissingUncompressedDigestAnnotation
 }
 
 extension VMDirectory {
   private static let bufferSizeBytes = 64 * 1024 * 1024
   private static let layerLimitBytes = 500 * 1000 * 1000
 
-  private static let configMediaType = "application/vnd.cirruslabs.tart.config.v1"
-  private static let diskMediaType = "application/vnd.cirruslabs.tart.disk.v1"
-  private static let nvramMediaType = "application/vnd.cirruslabs.tart.nvram.v1"
-
-  func pullFromRegistry(registry: Registry, reference: String) async throws {
-    defaultLogger.appendNewLine("pulling manifest...")
-
-    let (manifest, _) = try await registry.pullManifest(reference: reference)
-
-    return try await pullFromRegistry(registry: registry, manifest: manifest)
-  }
-
-  func pullFromRegistry(registry: Registry, manifest: OCIManifest) async throws {
+  func pullFromRegistry(registry: Registry, manifest: OCIManifest, concurrency: UInt, localLayerCache: LocalLayerCache?) async throws {
     // Pull VM's config file layer and re-serialize it into a config file
     let configLayers = manifest.layers.filter {
-      $0.mediaType == Self.configMediaType
+      $0.mediaType == configMediaType
     }
     if configLayers.count != 1 {
       throw OCIError.ShouldBeExactlyOneLayer
@@ -41,50 +31,42 @@ extension VMDirectory {
     }
     try configFile.close()
 
-    // Pull VM's disk layers and decompress them sequentially into a disk file
-    let diskLayers = manifest.layers.filter {
-      $0.mediaType == Self.diskMediaType
-    }
-    if diskLayers.isEmpty {
+    // Pull VM's disk layers and decompress them into a disk file
+    let diskImplType: Disk.Type
+    let layers: [OCIManifestLayer]
+
+    if manifest.layers.contains(where: { $0.mediaType == diskV1MediaType }) {
+      diskImplType = DiskV1.self
+      layers = manifest.layers.filter { $0.mediaType == diskV1MediaType }
+    } else if manifest.layers.contains(where: { $0.mediaType == diskV2MediaType }) {
+      diskImplType = DiskV2.self
+      layers = manifest.layers.filter { $0.mediaType == diskV2MediaType }
+    } else {
       throw OCIError.ShouldBeAtLeastOneLayer
     }
-    if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
-      throw OCIError.FailedToCreateVmFile
-    }
-    let disk = try FileHandle(forWritingTo: diskURL)
-    let filter = try OutputFilter(.decompress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { data in
-      if let data = data {
-        disk.write(data)
-      }
-    }
 
-    // Progress
-    let diskCompressedSize: Int64 = Int64(diskLayers.map {
-      $0.size
-    }
-    .reduce(0) {
-      $0 + $1
-    })
+    let diskCompressedSize = layers.map { Int64($0.size) }.reduce(0, +)
+    SentrySDK.span?.setMeasurement(name: "compressed_disk_size", value: diskCompressedSize as NSNumber, unit: MeasurementUnitInformation.byte)
+
     let prettyDiskSize = String(format: "%.1f", Double(diskCompressedSize) / 1_000_000_000.0)
     defaultLogger.appendNewLine("pulling disk (\(prettyDiskSize) GB compressed)...")
+
     let progress = Progress(totalUnitCount: diskCompressedSize)
     ProgressObserver(progress).log(defaultLogger)
 
-    for diskLayer in diskLayers {
-      try await registry.pullBlob(diskLayer.digest) { data in
-        try filter.write(data)
-        progress.completedUnitCount += Int64(data.count)
-      }
+    do {
+      try await diskImplType.pull(registry: registry, diskLayers: layers, diskURL: diskURL,
+                                  concurrency: concurrency, progress: progress,
+                                  localLayerCache: localLayerCache)
+    } catch let error where error is FilterError {
+      throw RuntimeError.PullFailed("failed to decompress disk: \(error.localizedDescription)")
     }
-    try filter.finalize()
-    try disk.close()
-    SentrySDK.span?.setMeasurement(name: "compressed_disk_size", value: diskCompressedSize as NSNumber, unit: MeasurementUnitInformation.byte);
 
     // Pull VM's NVRAM file layer and store it in an NVRAM file
     defaultLogger.appendNewLine("pulling NVRAM...")
 
     let nvramLayers = manifest.layers.filter {
-      $0.mediaType == Self.nvramMediaType
+      $0.mediaType == nvramMediaType
     }
     if nvramLayers.count != 1 {
       throw OCIError.ShouldBeExactlyOneLayer
@@ -97,9 +79,12 @@ extension VMDirectory {
       nvram.write(data)
     }
     try nvram.close()
+
+    // Serialize VM's manifest to enable better de-duplication on subsequent "tart pull"'s
+    try manifest.toJSON().write(to: manifestURL)
   }
 
-  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int) async throws -> RemoteName {
+  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int, diskFormat: String) async throws -> RemoteName {
     var layers = Array<OCIManifestLayer>()
 
     // Read VM's config and push it as blob
@@ -107,32 +92,22 @@ extension VMDirectory {
     let configJSON = try JSONEncoder().encode(config)
     defaultLogger.appendNewLine("pushing config...")
     let configDigest = try await registry.pushBlob(fromData: configJSON, chunkSizeMb: chunkSizeMb)
-    layers.append(OCIManifestLayer(mediaType: Self.configMediaType, size: configJSON.count, digest: configDigest))
+    layers.append(OCIManifestLayer(mediaType: configMediaType, size: configJSON.count, digest: configDigest))
 
-    // Progress
+    // Compress the disk file as multiple chunks and push them as disk layers
     let diskSize = try FileManager.default.attributesOfItem(atPath: diskURL.path)[.size] as! Int64
 
     defaultLogger.appendNewLine("pushing disk... this will take a while...")
     let progress = Progress(totalUnitCount: diskSize)
     ProgressObserver(progress).log(defaultLogger)
 
-    // Read VM's compressed disk as chunks
-    // and sequentially upload them as blobs
-    let mappedDisk = try Data(contentsOf: diskURL, options: [.alwaysMapped])
-    let mappedDiskSize = mappedDisk.count
-    var mappedDiskReadOffset = 0
-    let compressingFilter = try InputFilter(.compress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { (length: Int) -> Data? in
-      let bytesRead = min(length, mappedDiskSize - mappedDiskReadOffset)
-      let data = mappedDisk.subdata(in: mappedDiskReadOffset ..< mappedDiskReadOffset + bytesRead)
-      mappedDiskReadOffset += bytesRead
-
-      progress.completedUnitCount = Int64(mappedDiskReadOffset)
-
-      return data
-    }
-    while let compressedLayerData = try compressingFilter.readData(ofLength: Self.layerLimitBytes) {
-      let layerDigest = try await registry.pushBlob(fromData: compressedLayerData, chunkSizeMb: chunkSizeMb)
-      layers.append(OCIManifestLayer(mediaType: Self.diskMediaType, size: compressedLayerData.count, digest: layerDigest))
+    switch diskFormat {
+    case "v1":
+      layers.append(contentsOf: try await DiskV1.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, progress: progress))
+    case "v2":
+      layers.append(contentsOf: try await DiskV2.push(diskURL: diskURL, registry: registry, chunkSizeMb: chunkSizeMb, progress: progress))
+    default:
+      throw RuntimeError.OCIUnsupportedDiskFormat(diskFormat)
     }
 
     // Read VM's NVRAM and push it as blob
@@ -140,7 +115,7 @@ extension VMDirectory {
 
     let nvram = try FileHandle(forReadingFrom: nvramURL).readToEnd()!
     let nvramDigest = try await registry.pushBlob(fromData: nvram, chunkSizeMb: chunkSizeMb)
-    layers.append(OCIManifestLayer(mediaType: Self.nvramMediaType, size: nvram.count, digest: nvramDigest))
+    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()
@@ -148,7 +123,8 @@ extension VMDirectory {
     let manifest = OCIManifest(
       config: OCIManifestConfig(size: ociConfigJSON.count, digest: ociConfigDigest),
       layers: layers,
-      uncompressedDiskSize: UInt64(mappedDiskReadOffset)
+      uncompressedDiskSize: UInt64(diskSize),
+      uploadDate: Date()
     )
 
     // Manifest

Sources/tart/VMDirectory.swift

@@ -1,7 +1,14 @@
 import Foundation
 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 {
@@ -16,6 +23,9 @@ struct VMDirectory: Prunable {
   var stateURL: URL {
     baseURL.appendingPathComponent("state.vzvmsave")
   }
+  var manifestURL: URL {
+    baseURL.appendingPathComponent("manifest.json")
+  }
 
   var explicitlyPulledMark: URL {
     baseURL.appendingPathComponent(".explicitly-pulled")
@@ -29,26 +39,30 @@ struct VMDirectory: Prunable {
     baseURL
   }
 
+  func lock() throws -> PIDLock {
+    try PIDLock(lockURL: configURL)
+  }
+
   func running() throws -> Bool {
     // The most common reason why PIDLock() instantiation fails is a race with "tart delete" (ENOENT),
     // which is fine to report as "not running".
     //
     // The other reasons are unlikely and the cost of getting a false positive is way less than
     // the cost of crashing with an exception when calling "tart list" on a busy machine, for example.
-    guard let lock = try? PIDLock(lockURL: configURL) else {
+    guard let lock = try? lock() else {
       return false
     }
 
     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
     }
   }
 
@@ -59,6 +73,17 @@ struct VMDirectory: Prunable {
     return VMDirectory(baseURL: tmpDir)
   }
 
+  //Create tmp directory with hashing
+  static func temporaryDeterministic(key: String) throws -> VMDirectory {
+    let keyData = Data(key.utf8)
+    let hash = Insecure.MD5.hash(data: keyData)
+    // Convert hash to string
+    let hashString = hash.compactMap { String(format: "%02x", $0) }.joined()
+    let tmpDir = try Config().tartTmpDir.appendingPathComponent(hashString)
+    try FileManager.default.createDirectory(at: tmpDir, withIntermediateDirectories: true)
+    return VMDirectory(baseURL: tmpDir)
+  }
+
   var initialized: Bool {
     FileManager.default.fileExists(atPath: configURL.path) &&
       FileManager.default.fileExists(atPath: diskURL.path) &&
@@ -118,20 +143,45 @@ 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()
   }
 
   func delete() throws {
+    let lock = try lock()
+
+    if try !lock.trylock() {
+      throw RuntimeError.VMIsRunning(name)
+    }
+
     try FileManager.default.removeItem(at: baseURL)
+
+    try lock.unlock()
   }
 
   func accessDate() throws -> Date {
     try baseURL.accessDate()
   }
 
+  func allocatedSizeBytes() throws -> Int {
+    try configURL.allocatedSizeBytes() + diskURL.allocatedSizeBytes() + nvramURL.allocatedSizeBytes()
+  }
+
+  func allocatedSizeGB() throws -> Int {
+    try allocatedSizeBytes() / 1000 / 1000 / 1000
+  }
+
   func sizeBytes() throws -> Int {
     try configURL.sizeBytes() + diskURL.sizeBytes() + nvramURL.sizeBytes()
   }

Sources/tart/VMStorageHelper.swift

@@ -34,9 +34,15 @@ class VMStorageHelper {
   }
 }
 
+extension NSError {
+  func isFileNotFound() -> Bool {
+    return self.code == NSFileNoSuchFileError || self.code == NSFileReadNoSuchFileError
+  }
+}
+
 extension Error {
   func isFileNotFound() -> Bool {
-    (self as NSError).code == NSFileReadNoSuchFileError
+    (self as NSError).isFileNotFound() || (self as NSError).underlyingErrors.contains(where: { $0.isFileNotFound() })
   }
 }
 
@@ -44,21 +50,27 @@ enum RuntimeError : Error {
   case VMConfigurationError(_ message: String)
   case VMDoesNotExist(name: String)
   case VMMissingFiles(_ message: String)
-  case VMNotRunning(_ message: String)
+  case VMIsRunning(_ name: String)
+  case VMNotRunning(_ name: String)
   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 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)
   case ImportFailed(_ message: String)
   case SoftnetFailed(_ message: String)
   case OCIStorageError(_ message: String)
+  case OCIUnsupportedDiskFormat(_ format: String)
   case SuspendFailed(_ message: String)
+  case PullFailed(_ message: String)
 }
 
 protocol HasExitCode {
@@ -74,14 +86,20 @@ extension RuntimeError : CustomStringConvertible {
       return "the specified VM \"\(name)\" does not exist"
     case .VMMissingFiles(let message):
       return message
-    case .VMNotRunning(let message):
-      return message
+    case .VMIsRunning(let name):
+      return "VM \"\(name)\" is running"
+    case .VMNotRunning(let name):
+      return "VM \"\(name)\" is not running"
     case .VMAlreadyRunning(let message):
       return message
     case .NoIPAddressFound(let message):
       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):
@@ -90,6 +108,8 @@ extension RuntimeError : CustomStringConvertible {
       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):
@@ -102,8 +122,12 @@ extension RuntimeError : CustomStringConvertible {
       return "Softnet failed: \(message)"
     case .OCIStorageError(let message):
       return "OCI storage error: \(message)"
+    case .OCIUnsupportedDiskFormat(let format):
+      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
     }
   }
 }
@@ -111,6 +135,8 @@ extension RuntimeError : CustomStringConvertible {
 extension RuntimeError : HasExitCode {
   var exitCode: Int32 {
     switch self {
+    case .VMDoesNotExist:
+      return 2
     case .VMNotRunning:
       return 2
     case .VMAlreadyRunning:

Sources/tart/VMStorageLocal.swift

@@ -1,6 +1,6 @@
 import Foundation
 
-class VMStorageLocal {
+class VMStorageLocal: PrunableStorage {
   let baseURL: URL = try! Config().tartHomeDir.appendingPathComponent("vms", isDirectory: true)
 
   private func vmURL(_ name: String) -> URL {
@@ -16,6 +16,8 @@ class VMStorageLocal {
 
     try vmDir.validate(userFriendlyName: name)
 
+    try vmDir.baseURL.updateAccessDate()
+
     return vmDir
   }
 
@@ -37,7 +39,7 @@ class VMStorageLocal {
   }
 
   func delete(_ name: String) throws {
-    try FileManager.default.removeItem(at: vmURL(name))
+    try VMDirectory(baseURL: vmURL(name)).delete()
   }
 
   func list() throws -> [(String, VMDirectory)] {
@@ -63,6 +65,10 @@ class VMStorageLocal {
     }
   }
 
+  func prunables() throws -> [Prunable] {
+    try list().map { (_, vmDir) in vmDir }.filter { try !$0.running() }
+  }
+
   func hasVMsWithMACAddress(macAddress: String) throws -> Bool {
     try list().contains { try $1.macAddress() == macAddress }
   }

Sources/tart/VMStorageOCI.swift

@@ -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) async throws {
+  func pull(_ name: RemoteName, registry: Registry, concurrency: UInt) 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...")
@@ -170,7 +178,7 @@ class VMStorageOCI: PrunableStorage {
 
     if !exists(digestName) {
       let transaction = SentrySDK.startTransaction(name: name.description, operation: "pull", bindToScope: true)
-      let tmpVMDir = try VMDirectory.temporary()
+      let tmpVMDir = try VMDirectory.temporaryDeterministic(key: name.description)
 
       // Lock the temporary VM directory to prevent it's garbage collection
       let tmpVMDirLock = try FileLock(lockURL: tmpVMDir.baseURL)
@@ -188,7 +196,17 @@ class VMStorageOCI: PrunableStorage {
       }
 
       try await withTaskCancellationHandler(operation: {
-        try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest)
+        try await retry(maxAttempts: 5, backoff: .exponentialWithFullJitter(baseDelay: .seconds(5), maxDelay: .seconds(60))) {
+          // Choose the best base image which has the most deduplication ratio
+          let localLayerCache = try await chooseLocalLayerCache(name, manifest, registry)
+
+          try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest, concurrency: concurrency, localLayerCache: localLayerCache)
+        } recoverFromFailure: { error in
+          print("Error: \(error.localizedDescription)")
+          print("Attempting to re-try...")
+
+          return .retry
+        }
         try move(digestName, from: tmpVMDir)
         transaction.finish()
       }, onCancel: {
@@ -219,21 +237,70 @@ class VMStorageOCI: PrunableStorage {
   }
 
   func link(from: RemoteName, to: RemoteName) throws {
-    if FileManager.default.fileExists(atPath: vmURL(from).path) {
-      try FileManager.default.removeItem(at: vmURL(from))
-    }
+    try? FileManager.default.removeItem(at: vmURL(from))
 
     try FileManager.default.createSymbolicLink(at: vmURL(from), withDestinationURL: vmURL(to))
 
     try gc()
   }
+
+  func chooseLocalLayerCache(_ name: RemoteName, _ manifest: OCIManifest, _ registry: Registry) async throws -> LocalLayerCache? {
+    // Establish a closure that will calculate how much bytes
+    // we'll de-duplicate if we re-use the given manifest
+    let target = Swift.Set(manifest.layers)
+
+    let calculateDeduplicatedBytes = { (manifest: OCIManifest) -> Int in
+      target.intersection(manifest.layers).map({ $0.size }).reduce(0, +)
+    }
+
+    // Load OCI VM images and their manifests (if present)
+    var candidates: [(name: String, vmDir: VMDirectory, manifest: OCIManifest, deduplicatedBytes: Int)] = []
+
+    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 de-duplicate
+    let choosen = candidates.max { left, right in
+      return left.deduplicatedBytes < right.deduplicatedBytes
+    }
+
+    return try choosen.flatMap({ choosen in
+      try LocalLayerCache(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))
     }
 
@@ -241,6 +308,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!
+}

Sources/tart/VNC/FullFledgedVNC.swift

@@ -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

Sources/tart/VNC/ScreenSharingVNC.swift

@@ -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)")!

Sources/tart/VNC/VNC.swift

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

Tests/TartTests/DirecotryShareTests.swift

@@ -0,0 +1,74 @@
+import XCTest
+@testable import tart
+
+import Virtualization
+
+final class DirectoryShareTests: XCTestCase {
+  func testNamedParsing() throws {
+    let share = try DirectoryShare(parseFrom: "build:/Users/admin/build")
+    XCTAssertEqual(share.name, "build")
+    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")
+  }
+}

Tests/TartTests/DockerConfigTests.swift

@@ -0,0 +1,16 @@
+import XCTest
+@testable import tart
+
+final class DockerConfigTests: XCTestCase {
+  func testHelpers() throws {
+    let config = DockerConfig(credHelpers: [
+      "(.*).dkr.ecr.(.*).amazonaws.com": "ecr-login",
+      "gcr.io": "gcloud"
+    ])
+
+    XCTAssertEqual(try config.findCredHelper(host: "gcr.io"), "gcloud")
+    XCTAssertEqual(try config.findCredHelper(host: "123.dkr.ecr.eu-west-1.amazonaws.com"), "ecr-login")
+    XCTAssertEqual(try config.findCredHelper(host: "456.dkr.ecr.us-east-1.amazonaws.com"), "ecr-login")
+    XCTAssertNil(try config.findCredHelper(host: "ghcr.io"))
+  }
+}

Tests/TartTests/LayerizerTests.swift

@@ -0,0 +1,90 @@
+import XCTest
+@testable import tart
+
+final class LayerizerTests: XCTestCase {
+  var registryRunner: RegistryRunner?
+
+  var registry: Registry {
+    registryRunner!.registry
+  }
+
+  override func setUp() async throws {
+    try await super.setUp()
+
+    do {
+      registryRunner = try await RegistryRunner()
+    } catch {
+      try XCTSkipIf(ProcessInfo.processInfo.environment["CI"] == nil)
+    }
+  }
+
+  override func tearDown() async throws {
+    try await super.tearDown()
+
+    registryRunner = nil
+  }
+
+  func testDiskV1() async throws {
+    // Original disk file to be pushed to the registry
+    let originalDiskFileURL = try fileWithRandomData(sizeBytes: 5 * 1024 * 1024 * 1024)
+    addTeardownBlock {
+      try FileManager.default.removeItem(at: originalDiskFileURL)
+    }
+
+    // Disk file to be pulled from the registry
+    // and compared against the original disk file
+    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())
+
+    print("pulling disk...")
+    try await DiskV1.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())
+
+    print("comparing disks...")
+    try XCTAssertEqual(Digest.hash(originalDiskFileURL), Digest.hash(pulledDiskFileURL))
+  }
+
+  func testDiskV2() async throws {
+    // Original disk file to be pushed to the registry
+    let originalDiskFileURL = try fileWithRandomData(sizeBytes: 5 * 1024 * 1024 * 1024)
+    addTeardownBlock {
+      try FileManager.default.removeItem(at: originalDiskFileURL)
+    }
+
+    // Disk file to be pulled from the registry
+    // and compared against the original disk file
+    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())
+
+    print("pulling disk...")
+    try await DiskV2.pull(registry: registry, diskLayers: diskLayers, diskURL: pulledDiskFileURL, concurrency: 16, progress: Progress())
+
+    print("comparing disks...")
+    try XCTAssertEqual(Digest.hash(originalDiskFileURL), Digest.hash(pulledDiskFileURL))
+  }
+
+  private func fileWithRandomData(sizeBytes: Int) throws -> URL {
+    let devUrandom = try FileHandle(forReadingFrom: URL(filePath: "/dev/urandom"))
+
+    let temporaryFileURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+    FileManager.default.createFile(atPath: temporaryFileURL.path, contents: nil)
+    let temporaryFile = try FileHandle(forWritingTo: temporaryFileURL)
+
+    var remainingBytes = sizeBytes
+
+    while remainingBytes > 0 {
+      let randomData = try devUrandom.read(upToCount: min(64 * 1024 * 1024, remainingBytes))!
+      remainingBytes -= randomData.count
+      try temporaryFile.write(contentsOf: randomData)
+    }
+
+    try devUrandom.close()
+
+    try temporaryFile.close()
+
+    return temporaryFileURL
+  }
+}

Tests/TartTests/LeaseTest.swift

@@ -0,0 +1,18 @@
+import XCTest
+@testable import tart
+
+import Network
+import SwiftRadix
+
+final class LeaseTests: XCTestCase {
+  func testCorrectTimezone() throws {
+    let lease = Lease(fromRawLease: [
+      "hw_address": "1,11:22:33:44:55:66",
+      "ip_address": "1.2.3.4",
+      "lease": "0x6565da9e",
+    ])
+
+    XCTAssertNotNil(lease)
+    XCTAssertEqual(lease!.expiresAt.toISO(), "2023-11-28T12:18:38Z")
+  }
+}

Tests/TartTests/LeasesTests.swift

@@ -0,0 +1,61 @@
+import XCTest
+@testable import tart
+
+import Network
+import SwiftDate
+
+final class LeasesTests: XCTestCase {
+  func testNoExpired() throws {
+    let macAddress = MACAddress(fromString: "11:22:33:44:55:66")!
+
+    let leases = try Leases("""
+    {
+      name=whatever
+      ip_address=66.66.66.66
+      hw_address=1,\(macAddress)
+      identifier=1,\(macAddress)
+      lease=\(Int((Date() - 1.seconds).timeIntervalSince1970).hex)
+
+    }
+    {
+      name=whatever
+      ip_address=1.2.3.4
+      hw_address=1,\(macAddress)
+      identifier=1,\(macAddress)
+      lease=\(Int((Date() + 10.minutes).timeIntervalSince1970).hex)
+    }
+    {
+      name=whatever
+      ip_address=66.66.66.66
+      hw_address=1,\(macAddress)
+      identifier=1,\(macAddress)
+      lease=\(Int((Date() - 1.seconds).timeIntervalSince1970).hex)
+    }
+    """)
+
+    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))
+  }
+}

Tests/TartTests/MACAddressResolverTests.swift

@@ -8,11 +8,12 @@ final class MACAddressResolverTests: XCTestCase {
     {
       ip_address=1.2.3.4
       hw_address=1,00:11:22:33:44:55
+      lease=0x7fffffff
     }
     """)
 
     XCTAssertEqual(IPv4Address("1.2.3.4"),
-                   try leases.ResolveMACAddress(macAddress: MACAddress(fromString: "00:11:22:33:44:55")!))
+                   leases.ResolveMACAddress(macAddress: MACAddress(fromString: "00:11:22:33:44:55")!))
   }
 
   func testMultipleEntries() throws {
@@ -20,16 +21,18 @@ final class MACAddressResolverTests: XCTestCase {
     {
       ip_address=1.2.3.4
       hw_address=1,00:11:22:33:44:55
+      lease=0x7fffffff
     }
     {
       ip_address=5.6.7.8
       hw_address=1,AA:BB:CC:DD:EE:FF
+      lease=0x7fffffff
     }
     """)
 
     XCTAssertEqual(IPv4Address("1.2.3.4"),
-                   try leases.ResolveMACAddress(macAddress: MACAddress(fromString: "00:11:22:33:44:55")!))
+                   leases.ResolveMACAddress(macAddress: MACAddress(fromString: "00:11:22:33:44:55")!))
     XCTAssertEqual(IPv4Address("5.6.7.8"),
-                   try leases.ResolveMACAddress(macAddress: MACAddress(fromString: "AA:BB:CC:DD:EE:FF")!))
+                   leases.ResolveMACAddress(macAddress: MACAddress(fromString: "AA:BB:CC:DD:EE:FF")!))
   }
 }

Tests/TartTests/TokenResponseTests.swift

@@ -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())

Tests/TartTests/Util/RegistryRunner.swift

@@ -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

benchmark/.editorconfig

@@ -0,0 +1 @@
+root = true

benchmark/.golangci.yml

@@ -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

benchmark/README.md

@@ -0,0 +1,39 @@
+# 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, [install Golang](https://go.dev/) and run the following command from this (`benchmark/`) directory:
+
+```shell
+go run cmd/main.go fio
+```
+
+You can also enable the debugging output to diagnose issues:
+
+```shell
+go run cmd/main.go fio --debug
+```
+
+## Results
+
+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  
+```

benchmark/cmd/main.go

@@ -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()
+}

benchmark/go.mod

@@ -0,0 +1,29 @@
+module github.com/cirruslabs/tart/benchmark
+
+go 1.22.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/spf13/cobra v1.8.0
+	github.com/stretchr/testify v1.9.0
+	go.uber.org/zap v1.27.0
+	golang.org/x/crypto v0.21.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/fatih/color v1.16.0 // 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
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/sys v0.18.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

benchmark/go.sum

@@ -0,0 +1,52 @@
+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/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/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=
+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.21.0 h1:X31++rzVUdKhX5sWmSOFZxx8UW/ldWx55cbf08iNAMA=
+golang.org/x/crypto v0.21.0/go.mod h1:0BP7YvVV9gBbVKyeTG0Gyn+gZm94bibOW5BjDEYAOMs=
+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.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
+golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.18.0 h1:FcHjZXDMxI8mM3nwhX9HlKop4C0YQvCVCdwYl2wOtE8=
+golang.org/x/term v0.18.0/go.mod h1:ILwASektA3OnRv7amZ1xhE/KTR+u50pbXfZ03+6Nx58=
+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=

benchmark/internal/command/fio/benchmark.go

@@ -0,0 +1,29 @@
+package fio
+
+type Benchmark struct {
+	Name    string
+	Command string
+}
+
+var benchmarks = []Benchmark{
+	{
+		Name: "Random writing of 1MB",
+		Command: "fio --rw randwrite --runtime 30 --time_based --unlink 1 --output-format json " +
+			"--size 1MB --name unnamed --numjobs 1 --iodepth 1 --end_fsync 1",
+	},
+	{
+		Name: "Random writing of 10MB",
+		Command: "fio --rw randwrite --runtime 30 --time_based --unlink 1 --output-format json " +
+			"--size 10MB --name unnamed --numjobs 1 --iodepth 1 --end_fsync 1",
+	},
+	{
+		Name: "Random writing of 100MB",
+		Command: "fio --rw randwrite --runtime 30 --time_based --unlink 1 --output-format json " +
+			"--size 100MB --name unnamed --numjobs 1 --iodepth 1 --end_fsync 1",
+	},
+	{
+		Name: "Random writing of 1000MB",
+		Command: "fio --rw randwrite --runtime 30 --time_based --unlink 1 --output-format json " +
+			"--size 1000MB --name unnamed --numjobs 1 --iodepth 1 --end_fsync 1",
+	},
+}

benchmark/internal/command/fio/fio.go

@@ -0,0 +1,131 @@
+package fio
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"github.com/cirruslabs/tart/benchmark/internal/executor"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/local"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/tart"
+	"github.com/dustin/go-humanize"
+	"github.com/gosuri/uitable"
+	"github.com/spf13/cobra"
+	"go.uber.org/zap"
+)
+
+var debug bool
+
+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")
+
+	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()
+	}()
+
+	executors, err := initializeExecutors(cmd.Context(), logger)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		errs := []error{err}
+
+		for _, executor := range executors {
+			if err := executor.Close(); err != nil {
+				errs = append(errs, fmt.Errorf("failed to close executor %s: %w", executor.Name(), err))
+			}
+		}
+
+		err = errors.Join(errs...)
+	}()
+
+	table := uitable.New()
+	table.AddRow("Name", "Executor", "Bandwidth", "I/O operations")
+
+	for _, benchmark := range benchmarks {
+		for _, executor := range executors {
+			logger.Sugar().Infof("running benchmark %q on %s executor", benchmark.Name, executor.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]
+
+			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\n", writeBandwidth, writeIOPS)
+
+			table.AddRow(benchmark.Name, executor.Name(), writeBandwidth, writeIOPS)
+		}
+	}
+
+	fmt.Println(table.String())
+
+	return nil
+}
+
+func initializeExecutors(ctx context.Context, logger *zap.Logger) ([]executor.Executor, error) {
+	var result []executor.Executor
+
+	logger.Info("initializing local executor")
+
+	local, err := local.New(logger)
+	if err != nil {
+		return nil, err
+	}
+	result = append(result, local)
+
+	logger.Info("local executor initialized")
+
+	logger.Info("initializing Tart executor")
+
+	tart, err := tart.New(ctx, logger)
+	if err != nil {
+		return nil, err
+	}
+	result = append(result, tart)
+
+	logger.Info("Tart executor initialized")
+
+	for _, executor := range result {
+		logger.Sugar().Infof("installing Flexible I/O tester (fio) on %s executor", executor.Name())
+
+		if _, err := executor.Run(ctx, "brew install fio"); err != nil {
+			return nil, err
+		}
+	}
+
+	return result, nil
+}

benchmark/internal/command/fio/json.go

@@ -0,0 +1,15 @@
+package fio
+
+type Result struct {
+	Jobs []Job `json:"jobs"`
+}
+
+type Job struct {
+	Name  string `json:"jobname"`
+	Write Write  `json:"write"`
+}
+
+type Write struct {
+	BW   float64 `json:"bw"`
+	IOPS float64 `json:"iops"`
+}

benchmark/internal/command/root.go

@@ -0,0 +1,20 @@
+package command
+
+import (
+	"github.com/cirruslabs/tart/benchmark/internal/command/fio"
+	"github.com/spf13/cobra"
+)
+
+func NewCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:           "benchmark",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+
+	cmd.AddCommand(
+		fio.NewCommand(),
+	)
+
+	return cmd
+}

benchmark/internal/executor/executor.go

@@ -0,0 +1,11 @@
+package executor
+
+import (
+	"context"
+)
+
+type Executor interface {
+	Name() string
+	Run(ctx context.Context, command string) ([]byte, error)
+	Close() error
+}

benchmark/internal/executor/local/local.go

@@ -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
+}

benchmark/internal/executor/local/local_test.go

@@ -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())
+}

benchmark/internal/executor/tart/cmd.go

@@ -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
+}

benchmark/internal/executor/tart/tart.go

@@ -0,0 +1,133 @@
+package tart
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"github.com/avast/retry-go/v4"
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+	"golang.org/x/crypto/ssh"
+	"net"
+	"strings"
+	"time"
+)
+
+const baseImage = "ghcr.io/cirruslabs/macos-sonoma-base:latest"
+
+type Tart struct {
+	vmRunCancel context.CancelFunc
+	vmName      string
+	sshClient   *ssh.Client
+	logger      *zap.Logger
+}
+
+func New(ctx context.Context, logger *zap.Logger) (*Tart, error) {
+	tart := &Tart{
+		vmName: fmt.Sprintf("tart-benchmark-%s", uuid.NewString()),
+		logger: logger,
+	}
+
+	if err := Cmd(ctx, tart.logger, "pull", baseImage); err != nil {
+		return nil, err
+	}
+
+	if err := Cmd(ctx, tart.logger, "clone", baseImage, tart.vmName); err != nil {
+		return nil, err
+	}
+
+	vmRunCtx, vmRunCancel := context.WithCancel(ctx)
+	tart.vmRunCancel = vmRunCancel
+
+	go func() {
+		_ = Cmd(vmRunCtx, tart.logger, "run", "--no-graphics", tart.vmName)
+	}()
+
+	ip, err := CmdWithOutput(ctx, tart.logger, "ip", "--wait", "60", tart.vmName)
+	if err != nil {
+		return nil, tart.Close()
+	}
+
+	err = retry.Do(func() error {
+		dialer := net.Dialer{
+			Timeout: 1 * time.Second,
+		}
+
+		addr := fmt.Sprintf("%s:22", strings.TrimSpace(ip))
+
+		netConn, err := dialer.DialContext(ctx, "tcp", addr)
+		if err != nil {
+			return err
+		}
+
+		sshConn, chans, reqs, err := ssh.NewClientConn(netConn, addr, &ssh.ClientConfig{
+			User: "admin",
+			Auth: []ssh.AuthMethod{
+				ssh.Password("admin"),
+			},
+			HostKeyCallback: func(_ string, _ net.Addr, _ ssh.PublicKey) error {
+				return nil
+			},
+		})
+		if err != nil {
+			return err
+		}
+
+		tart.sshClient = ssh.NewClient(sshConn, chans, reqs)
+
+		return nil
+	}, retry.RetryIf(func(err error) bool {
+		return !errors.Is(err, context.Canceled)
+	}))
+	if err != nil {
+		return nil, tart.Close()
+	}
+
+	return tart, nil
+}
+
+func (tart *Tart) Name() string {
+	return "Tart"
+}
+
+func (tart *Tart) Run(ctx context.Context, command string) ([]byte, error) {
+	sshSession, err := tart.sshClient.NewSession()
+	if err != nil {
+		return nil, err
+	}
+
+	// Work around x/crypto/ssh not being context.Context-friendly (e.g. https://github.com/golang/go/issues/20288)
+	monitorCtx, monitorCancel := context.WithCancel(ctx)
+	go func() {
+		<-monitorCtx.Done()
+		_ = sshSession.Close()
+	}()
+	defer monitorCancel()
+
+	stdoutBuf := &bytes.Buffer{}
+
+	sshSession.Stdin = bytes.NewBufferString(command)
+	sshSession.Stdout = stdoutBuf
+
+	if err := sshSession.Shell(); err != nil {
+		return nil, err
+	}
+
+	if err := sshSession.Wait(); err != nil {
+		return nil, err
+	}
+
+	return stdoutBuf.Bytes(), nil
+}
+
+func (tart *Tart) Close() error {
+	if tart.sshClient != nil {
+		_ = tart.sshClient.Close()
+	}
+
+	tart.vmRunCancel()
+	_ = Cmd(context.Background(), tart.logger, "delete", tart.vmName)
+
+	return nil
+}

benchmark/internal/executor/tart/tart_test.go

@@ -0,0 +1,22 @@
+package tart_test
+
+import (
+	"context"
+	"github.com/cirruslabs/tart/benchmark/internal/executor/tart"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"testing"
+)
+
+func TestTart(t *testing.T) {
+	ctx := context.Background()
+
+	tart, err := tart.New(ctx, zap.NewNop())
+	require.NoError(t, err)
+
+	output, err := tart.Run(ctx, "echo \"this is a test\"")
+	require.NoError(t, err)
+	require.Equal(t, "this is a test\n", string(output))
+
+	require.NoError(t, tart.Close())
+}

docs/.markdownlint.yml

@@ -0,0 +1,12 @@
+"default": true
+"MD002": false # First heading should be a top level heading
+"MD007": # Unordered list indentation
+  indent: 4
+"MD009": false # Trailing spaces
+"MD013": false # Line length
+"MD025": false # Multiple top level headings in the same document
+"MD026": false # Trailing punctuation in heading
+"MD033": false # Inline HTML
+"MD041": false # First line in file should be a top level heading
+"MD045": false # OK not to have a description for an image
+"MD046": false #  Code block style [Expected: fenced; Actual: indented]

docs/blog/.authors.yml

@@ -1,8 +1,9 @@
-edigaryev:
-  name: Nikolay Edigaryev
-  description: Creator
-  avatar: https://github.com/edigaryev.png
-fkorotkov:
-  name: Fedor Korotkov
-  description: Creator
-  avatar: https://github.com/fkorotkov.png
+authors:
+  edigaryev:
+    name: Nikolay Edigaryev
+    description: Creator
+    avatar: https://github.com/edigaryev.png
+  fkorotkov:
+    name: Fedor Korotkov
+    description: Creator
+    avatar: https://github.com/fkorotkov.png