Improve available capacity checking (#240)

* Improve available capacity checking

* Fixed expression

.ci/create-pkg.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+set -e
+
+export VERSION="${CIRRUS_TAG:-0}"
+
+mkdir -p .ci/pkg/
+cp .build/arm64-apple-macosx/debug/tart .ci/pkg/
+pkgbuild --root .ci/pkg --version $VERSION --install-location /usr/local/bin/ --identifier com.github.cirruslabs.tart --sign "Developer ID Installer: Fedor Korotkov (9M2P8L4D89)" "./dist/Tart-$VERSION.pkg"
+xcrun notarytool submit "./dist/Tart-$VERSION.pkg" --keychain-profile "notarytool" --wait
+xcrun stapler staple "./dist/Tart-$VERSION.pkg"

.ci/set-version.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+TMPFILE=$(mktemp)
+envsubst < Sources/tart/CI/CI.swift > $TMPFILE
+mv $TMPFILE Sources/tart/CI/CI.swift

.cirrus.yml

@@ -1,14 +1,16 @@
-persistent_worker:
-  labels:
-    name: Mac-Mini-M1
-
 task:
-  name: Test
+  name: Test on Ventura
+  persistent_worker:
+    labels:
+      name: Mac-Mini-M1
+  build_script: swift test
   test_script: swift test
 
 task:
   name: Build
   only_if: $CIRRUS_TAG == ''
+  macos_instance:
+    image: ghcr.io/cirruslabs/macos-ventura-xcode:latest
   build_script: swift build --product tart
   sign_script: codesign --sign - --entitlements Resources/tart.entitlements --force .build/debug/tart
   binary_artifacts:
@@ -17,7 +19,27 @@ task:
 task:
   name: Release
   only_if: $CIRRUS_TAG != ''
+  macos_instance:
+    image: ghcr.io/cirruslabs/macos-ventura-xcode:latest
   env:
+    MACOS_CERTIFICATE: ENCRYPTED[8a6930a8c1286e7e536ea41b7647ea40e99174ad15e9cfcc753754fea55a619b355415629dff515b54a8921643e314e5]
+    AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2]
     GITHUB_TOKEN: ENCRYPTED[!98ace8259c6024da912c14d5a3c5c6aac186890a8d4819fad78f3e0c41a4e0cd3a2537dd6e91493952fb056fa434be7c!]
     GORELEASER_KEY: ENCRYPTED[!9b80b6ef684ceaf40edd4c7af93014ee156c8aba7e6e5795f41c482729887b5c31f36b651491d790f1f668670888d9fd!]
+  setup_script:
+    - cd $HOME
+    - echo $MACOS_CERTIFICATE | base64 --decode > certificate.p12
+    - security create-keychain -p password101 build.keychain
+    - security default-keychain -s build.keychain
+    - security unlock-keychain -p password101 build.keychain
+    - security import certificate.p12 -k build.keychain -P password101 -T /usr/bin/codesign -T /usr/bin/pkgbuild
+    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
+    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
+  install_script: 
+    - brew install go goreleaser/tap/goreleaser-pro
+    - brew install mitchellh/gon/gon
+  info_script:
+    - security find-identity -v
+    - xcodebuild -version
+    - swift -version
   release_script: goreleaser

.goreleaser.yml

@@ -7,12 +7,16 @@ builds:
     goarch:
       - arm64
     prebuilt:
-      path: .build/{{ .Arch }}-apple-macosx/release/tart
+      path: .build/arm64-apple-macosx/debug/tart 
+    hooks:
+      post: 
+        - gon gon.hcl
+        - .ci/create-pkg.sh
 
 before:
   hooks:
-    - swift build -c release --product tart
-    - codesign --sign - --entitlements Resources/tart.entitlements --force .build/arm64-apple-macosx/release/tart
+    - .ci/set-version.sh
+    - swift build -c debug --product tart
 
 archives:
   - id: binary
@@ -23,6 +27,8 @@ archives:
 
 release:
   prerelease: auto
+  extra_files:
+    - glob: ./dist/Tart-{{ .Tag }}.pkg
 
 brews:
   - name: tart
@@ -31,9 +37,17 @@ brews:
     tap:
       owner: cirruslabs
       name: homebrew-cli
-    caveats: See the Github repository for more information
+    caveats: See the GitHub repository for more information
     homepage: https://github.com/cirruslabs/tart
     description: Run macOS VMs on Apple Silicon
     skip_upload: auto
+    dependencies:
+      - "cirruslabs/cli/softnet"
     custom_block: |
       depends_on :macos => :monterey
+      
+      on_macos do
+        unless Hardware::CPU.arm?
+          odie "Tart only works on Apple Silicon!"
+        end
+      end

Package.resolved

@@ -1,5 +1,32 @@
 {
   "pins" : [
+    {
+      "identity" : "async-http-client",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swift-server/async-http-client",
+      "state" : {
+        "revision" : "df87a860fdc41a595d5ca67f74cde9adbccc099a",
+        "version" : "1.11.4"
+      }
+    },
+    {
+      "identity" : "dynamic",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/mhdhejazi/Dynamic",
+      "state" : {
+        "branch" : "master",
+        "revision" : "772883073d044bc754d401cabb6574624eb3778f"
+      }
+    },
+    {
+      "identity" : "swift-algorithms",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-algorithms",
+      "state" : {
+        "revision" : "b14b7f4c528c942f121c8b860b9410b2bf57825e",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "swift-argument-parser",
       "kind" : "remoteSourceControl",
@@ -9,6 +36,15 @@
         "version" : "1.1.2"
       }
     },
+    {
+      "identity" : "swift-atomics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-atomics.git",
+      "state" : {
+        "revision" : "919eb1d83e02121cdb434c7bfc1f0c66ef17febe",
+        "version" : "1.0.2"
+      }
+    },
     {
       "identity" : "swift-case-paths",
       "kind" : "remoteSourceControl",
@@ -18,6 +54,69 @@
         "version" : "0.8.1"
       }
     },
+    {
+      "identity" : "swift-log",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-log.git",
+      "state" : {
+        "revision" : "5d66f7ba25daf4f94100e7022febf3c75e37a6c7",
+        "version" : "1.4.2"
+      }
+    },
+    {
+      "identity" : "swift-nio",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio.git",
+      "state" : {
+        "revision" : "124119f0bb12384cef35aa041d7c3a686108722d",
+        "version" : "2.40.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-extras",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-extras.git",
+      "state" : {
+        "revision" : "8eea84ec6144167354387ef9244b0939f5852dc8",
+        "version" : "1.11.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-http2",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-http2.git",
+      "state" : {
+        "revision" : "108ac15087ea9b79abb6f6742699cf31de0e8772",
+        "version" : "1.22.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-ssl",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-ssl.git",
+      "state" : {
+        "revision" : "1750873bce84b4129b5303655cce2c3d35b9ed3a",
+        "version" : "2.19.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-transport-services",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-transport-services.git",
+      "state" : {
+        "revision" : "1a4692acb88156e3da1b0c6732a8a38b2a744166",
+        "version" : "1.12.0"
+      }
+    },
+    {
+      "identity" : "swift-numerics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-numerics",
+      "state" : {
+        "revision" : "0a5bc04095a675662cf24757cc0640aa2204253b",
+        "version" : "1.0.2"
+      }
+    },
     {
       "identity" : "swift-parsing",
       "kind" : "remoteSourceControl",
@@ -27,6 +126,15 @@
         "version" : "0.9.2"
       }
     },
+    {
+      "identity" : "swiftdate",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/malcommac/SwiftDate",
+      "state" : {
+        "revision" : "6190d0cefff3013e77ed567e6b074f324e5c5bf5",
+        "version" : "6.3.1"
+      }
+    },
     {
       "identity" : "xctest-dynamic-overlay",
       "kind" : "remoteSourceControl",

Package.swift

@@ -1,7 +1,6 @@
-// swift-tools-version:5.6
+// swift-tools-version:5.7
 
 import PackageDescription
-
 let package = Package(
   name: "Tart",
   platforms: [
@@ -12,13 +11,22 @@ let package = Package(
   ],
   dependencies: [
     .package(url: "https://github.com/apple/swift-argument-parser", from: "1.1.2"),
+    .package(url: "https://github.com/mhdhejazi/Dynamic", branch: "master"),
     .package(url: "https://github.com/pointfreeco/swift-parsing", from: "0.9.2"),
+    .package(url: "https://github.com/swift-server/async-http-client", from: "1.11.4"),
+    .package(url: "https://github.com/apple/swift-algorithms", from: "1.0.0"),
+    .package(url: "https://github.com/malcommac/SwiftDate", from: "6.3.1")
   ],
   targets: [
     .executableTarget(name: "tart", dependencies: [
+      .product(name: "Algorithms", package: "swift-algorithms"),
       .product(name: "ArgumentParser", package: "swift-argument-parser"),
+      .product(name: "AsyncHTTPClient", package: "async-http-client"),
+      .product(name: "Dynamic", package: "Dynamic"),
       .product(name: "Parsing", package: "swift-parsing"),
+      .product(name: "SwiftDate", package: "SwiftDate"),
     ]),
     .testTarget(name: "TartTests", dependencies: ["tart"])
   ]
 )
+

README.md

@@ -1,13 +1,29 @@
 ![Tart – open source virtualization for your automation needs](Resources/TartSocial.png)
 
-*Tart* is a virtualization toolset to build, run and manage virtual machines on Apple Silicon.
+*Tart* is a virtualization toolset to build, run and manage macOS and Linux virtual machines on Apple Silicon.
 Built by CI engineers for your automation needs. Here are some highlights of Tart:
 
-* Tart uses Apple's own `Virtualization.Framework` for near-native performance.
+* Tart uses Apple's own `Virtualization.Framework` for [near-native performance](https://browser.geekbench.com/v5/cpu/compare/14966395?baseline=14966339).
 * Push/Pull virtual machines from any OCI-compatible container registry.
 * Use Tart Packer Plugin to automate VM creation.
 * Built-in CI integration.
 
+*Tart* is already adopted by several automation services:
+
+<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>
+</p>
+
+## Usage
+
 Try running a Tart VM on your Apple Silicon device running macOS Monterey or later (will download a 25 GB image):
 
 ```shell
@@ -20,9 +36,13 @@ tart run monterey-base
 
 ## CI Integration
 
-[Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) is an open-sourced CI-agnostic tool that can run workloads
-inside containers via Docker or Podman and now inside macOS VMs via Tart. Put the following `.cirrus.yml` file
-in the root of your repository:
+Tart itself is only responsible for managing virtual machines, but we've built Tart support into a tool called Cirrus CLI
+also developed by Cirrus Labs. [Cirrus CLI](https://github.com/cirruslabs/cirrus-cli) is a command line tool with
+one configuration format to execute common CI steps (run a script, cache a folder, etc.) locally or in any CI system.
+We built Cirrus CLI to solve "But it works on my machine!" problem.
+
+Here is an example of a `.cirrus.yml` configuration file which will start a Tart VM, will copy over working directory and
+will run scripts and [other instructions](https://cirrus-ci.org/guide/writing-tasks/#supported-instructions) inside the virtual machine:
 
 ```yaml
 task:
@@ -37,7 +57,7 @@ task:
     - sleep 15
 ```
 
-Run it locally or in CI with the following command:
+Put the above `.cirrus.yml` file in the root of your repository and run it with the following command:
 
 ```shell
 brew install cirruslabs/cli/cirrus
@@ -51,10 +71,40 @@ config from above will just work in Cirrus CI and your tasks will be executed in
 
 **Note:** Cirrus CI only allows [images managed and regularly updated by us](https://github.com/orgs/cirruslabs/packages?tab=packages&q=macos).
 
+### Retrieving artifacts from within Tart VMs
+
+In many cases there is a need to retrieve particular files or a folder from within a Tart virtual machine.
+For example, the below `.cirrus.yml` configuration defines a single task that builds a `tart` binary and
+exposes it via [`artifacts` instruction](https://cirrus-ci.org/guide/writing-tasks/#artifacts-instruction):
+
+```yaml
+task:
+  name: Build
+  macos_instance:
+    image: ghcr.io/cirruslabs/macos-monterey-xcode:latest
+  build_script: swift build --product tart
+  binary_artifacts:
+    path: .build/debug/tart
+```
+
+Running Cirrus CLI with `--artifacts-dir` will write defined `artifacts` to the provided local directory on the host:
+
+```bash
+cirrus run --artifacts-dir artifacts
+```
+
+Note that all retrieved artifacts will be prefixed with the associated task name and `artifacts` instruction name.
+For the example above, `tart` binary will be saved to `$PWD/artifacts/Build/binary/.build/debug/tart`.
+
 ## Virtual Machine Management
 
 ### Creating from scratch
 
+Tart supports macOS and Linux virtual machines. All commands like `run` and `pull` work the same way regarding of the underlying OS a particular VM image has.
+The only difference is how such VM images are created. Please check sections below for [macOS](#creating-a-macos-vm-image-from-scratch) and [Linux](#creating-a-linux-vm-image-from-scratch) instructions.
+
+#### Creating a macOS VM image from scratch
+
 Tart can create VMs from `*.ipsw` files. You can download a specific `*.ipsw` file [here](https://ipsw.me/) or you can
 use `latest` instead of a path to `*.ipsw` to download the latest available version:
 
@@ -71,6 +121,27 @@ After the initial booting of the VM you'll need to manually go through the macOS
 4. Disable Screen Saver.
 5. Run `sudo visudo` in Terminal, find `%admin ALL=(ALL) ALL` add `admin ALL=(ALL) NOPASSWD: ALL` to allow sudo without a password.
 
+#### Creating a Linux VM image from scratch
+
+```bash
+# Create a bare VM
+tart create --linux ubuntu
+
+# Install Ubuntu
+tart run --disk focal-desktop-arm64.iso ubuntu
+
+# Run VM
+tart run ubuntu
+```
+
+After the initial setup please make sure your VM can be SSH-ed into by running the following commands inside your VM:
+
+```shell
+sudo apt update
+sudo apt install -y openssh-server
+sudo ufw allow ssh
+```
+
 ### Configuring a VM
 
 By default, a tart VM uses 2 CPUs and 4 GB of memory with a `1024x768` display. This can be changed with `tart set` command.
@@ -136,10 +207,20 @@ tart push my-local-vm-name acme.io/remoteorg/name:latest acme.io/remoteorg/name:
 
 #### Pulling a Remote Image
 
+You can either pull an image:
+
 ```shell
-tart pull acme.io/remoteorg/name:latest my-local-vm-name
+tart pull acme.io/remoteorg/name:latest
 ```
 
+...or instantiate a VM from a remote image:
+
+```shell
+tart clone acme.io/remoteorg/name:latest my-local-vm-name
+```
+
+This invocation calls the `tart pull` implicitly (if the image is not being present) before doing the actual cloning.
+
 ## FAQ
 
 <details>
@@ -174,9 +255,34 @@ tart pull acme.io/remoteorg/name:latest my-local-vm-name
   disk size for new virtual machines. Here is an example of [how to change disk size in a Packer template](https://github.com/cirruslabs/macos-image-templates/blob/fb0bcf68e0b093129136875c050205a66729b596/templates/base.pkr.hcl#L15).
 </details>
 
+<details>
+  <summary>VM location on disk</summary>
+
+  Tart stores all it's files in `~/.tart/` directory. Local images that you can run are stored in `~/.tart/vms/`.
+  Remote images are pulled into `~/.tart/vms/cache/OCIs/`.
+</details>
+
 <details>
   <summary>Nested virtualization support?</summary>
 
   Tart is limited by functionality of Apple's `Virtualization.Framework`. At the moment `Virtualization.Framework`
   doesn't support nested virtualization.
 </details>
+
+<details>
+  <summary>Changing the default NAT subnet</summary>
+
+  To change the default network to `192.168.77.1`:
+
+  ```
+  sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.vmnet.plist Shared_Net_Address -string 192.168.77.1
+  ```
+
+  Note that even through a network would normally be specified as `192.168.77.0`, the [vmnet framework](https://developer.apple.com/documentation/vmnet) seems to treat this as a starting address too and refuses to pick up such network-like values.
+
+  The default subnet mask `255.255.255.0` should suffice for most use-cases, however, you can also change it to `255.255.0.0`, for example:
+
+  ```
+  sudo defaults write /Library/Preferences/SystemConfiguration/com.apple.vmnet.plist Shared_Net_Mask -string 255.255.0.0
+  ```
+</details>

Resources/AppIcon.png

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:8dd6af1a08bbcdc4faf0ff53601b38136c90231e11bd81bc8cd477d6f1c7d3f2
-size 209404
+oid sha256:1fe96aed7a965b075300f092a3ca76e09053eb7cf2f3125c3a819098a8bc4b31
+size 123360

Resources/Users/CirrusCI.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dbcf6f65f26c0e17b2fe55a9712fc783315cd64905a0febce758b31d7e4e923b
+size 6787

Resources/Users/Codemagic.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4239996f30145992936cfc8faa0232fa8904aedf4de61e30ef4c4fc86cad587f
+size 14588

Resources/Users/TestingBot.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:227192fcd215c9cc05b1ebcd2616bd1f8c95be184726f64d91fc4507a88c66e1
+size 18393

Sources/tart/ARP/ARPCache.swift

@@ -1,119 +0,0 @@
-import Foundation
-import Network
-import Virtualization
-
-struct ARPCommandFailedError: Error, CustomStringConvertible {
-  var terminationReason: Process.TerminationReason
-  var terminationStatus: Int32
-
-  var description: String {
-    var reason: String
-
-    switch terminationReason {
-    case .exit:
-      reason = "exit code \(terminationStatus)"
-    case .uncaughtSignal:
-      reason = "uncaught signal"
-    default:
-      reason = "unknown reason"
-    }
-
-    return "arp command failed: \(reason)"
-  }
-}
-
-struct ARPCommandYieldedInvalidOutputError: Error, CustomStringConvertible {
-  var explanation: String
-
-  var description: String {
-    "arp command yielded invalid output: \(explanation)"
-  }
-}
-
-struct ARPCacheInternalError: Error, CustomStringConvertible {
-  var explanation: String
-
-  var description: String {
-    "ARPCache internal error: \(explanation)"
-  }
-}
-
-struct ARPCache {
-  static func ResolveMACAddress(macAddress: MACAddress, bridgeOnly: Bool = true) throws -> IPv4Address? {
-    let process = Process.init()
-    process.executableURL = URL.init(fileURLWithPath: "/usr/sbin/arp")
-    process.arguments = ["-an"]
-
-    let pipe = Pipe()
-    process.standardOutput = pipe
-    process.standardError = pipe
-    process.standardInput = FileHandle.nullDevice
-
-    try process.run()
-    process.waitUntilExit()
-
-    if !(process.terminationReason == .exit && process.terminationStatus == 0) {
-      throw ARPCommandFailedError(
-        terminationReason: process.terminationReason,
-        terminationStatus: process.terminationStatus)
-    }
-
-    guard let rawLines = try pipe.fileHandleForReading.readToEnd() else {
-      throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
-    }
-    let lines = String(decoding: rawLines, as: UTF8.self)
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-            .components(separatedBy: "\n")
-
-    // Based on https://opensource.apple.com/source/network_cmds/network_cmds-606.40.2/arp.tproj/arp.c.auto.html
-    let regex = try NSRegularExpression(pattern: #"^.* \((?<ip>.*)\) at (?<mac>.*) on (?<interface>.*) .*$"#)
-
-    for line in lines {
-      let nsLineRange = NSRange(line.startIndex..<line.endIndex, in: line)
-
-      guard let match = regex.firstMatch(in: line, range: nsLineRange) else {
-        throw ARPCommandYieldedInvalidOutputError(explanation: "unparseable entry \"\(line)\"")
-      }
-
-      let rawIP = try match.getCaptureGroup(name: "ip", for: line)
-      guard let ip = IPv4Address(rawIP) else {
-        throw ARPCommandYieldedInvalidOutputError(explanation: "failed to parse IPv4 address \(rawIP)")
-      }
-
-      let rawMAC = try match.getCaptureGroup(name: "mac", for: line)
-      if rawMAC == "(incomplete)" {
-        continue
-      }
-      guard let mac = MACAddress(fromString: rawMAC) else {
-        throw ARPCommandYieldedInvalidOutputError(explanation: "failed to parse MAC address \(rawMAC)")
-      }
-
-      let interface = try match.getCaptureGroup(name: "interface", for: line)
-      if bridgeOnly && !interface.starts(with: "bridge") {
-        continue
-      }
-
-      if macAddress == mac {
-        return ip
-      }
-    }
-
-    return nil
-  }
-}
-
-extension NSTextCheckingResult {
-  func getCaptureGroup(name: String, for string: String) throws -> String {
-    let nsRange = self.range(withName: name)
-
-    if nsRange.location == NSNotFound {
-      throw ARPCacheInternalError(explanation: "attempted to retrieve non-existent named capture group \(name)")
-    }
-
-    guard let range = Range.init(nsRange, in: string) else {
-      throw ARPCacheInternalError(explanation: "failed to convert NSRange to Range")
-    }
-
-    return String(string[range])
-  }
-}

Sources/tart/CI/CI.swift

@@ -0,0 +1,13 @@
+struct CI {
+  private static let rawVersion = "${CIRRUS_TAG}"
+
+  static var version: String {
+    rawVersion.expanded() ? rawVersion : "SNAPSHOT"
+  }
+}
+
+private extension String {
+  func expanded() -> Bool {
+    !isEmpty && !starts(with: "$")
+  }
+}

Sources/tart/Commands/Clone.swift

@@ -11,24 +11,47 @@ struct Clone: AsyncParsableCommand {
   @Argument(help: "new VM name")
   var newName: String
 
+  @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
+  var insecure: Bool = false
+
+  func validate() throws {
+    if newName.contains("/") {
+      throw ValidationError("<new-name> should be a local name")
+    }
+  }
+
   func run() async throws {
     do {
-      if let remoteName = try? RemoteName(sourceName) {
-        if !VMStorageOCI().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)
-          try await VMStorageOCI().pull(remoteName, registry: registry)
-        }
-        let remoteVM = try VMStorageHelper.open(sourceName)
+      let ociStorage = VMStorageOCI()
+      let localStorage = VMStorageLocal()
 
-        let remoteConfig = try VMConfig.init(fromURL: remoteVM.configURL)
-        let needToGenerateNewMAC = try localVMExistsWith(macAddress: remoteConfig.macAddress.string)
-
-        try remoteVM.clone(to: VMStorageLocal().create(newName), generateMAC: needToGenerateNewMAC)
-      } else {
-        try VMStorageHelper.open(sourceName).clone(to: VMStorageLocal().create(newName), generateMAC: true)
+      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)
       }
 
+      let sourceVM = try VMStorageHelper.open(sourceName)
+
+      let tmpVMDir = try VMDirectory.temporary()
+
+      // Lock the temporary VM directory to prevent it's garbage collection
+      let tmpVMDirLock = try FileLock(lockURL: tmpVMDir.baseURL)
+      try tmpVMDirLock.lock()
+
+      try await withTaskCancellationHandler(operation: {
+        let lock = try FileLock(lockURL: Config().tartHomeDir)
+        try lock.lock()
+
+        let generateMAC = try localStorage.hasVMsWithMACAddress(macAddress: sourceVM.macAddress())
+        try sourceVM.clone(to: tmpVMDir, generateMAC: generateMAC)
+        try localStorage.move(newName, from: tmpVMDir)
+
+        try lock.unlock()
+      }, onCancel: {
+        try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+      })
+
       Foundation.exit(0)
     } catch {
       print(error)
@@ -36,15 +59,16 @@ struct Clone: AsyncParsableCommand {
       Foundation.exit(1)
     }
   }
+}
 
-  private func localVMExistsWith(macAddress: String) throws -> Bool {
-    var needToGenerateNewMAC = false
-    for (_, localDir) in try VMStorageLocal().list() {
-      let localConfig = try VMConfig.init(fromURL: localDir.configURL)
-      if localConfig.macAddress.string == macAddress {
-        needToGenerateNewMAC = true
-      }
-    }
-    return needToGenerateNewMAC
+fileprivate extension VMDirectory {
+  func macAddress() throws -> String {
+    try VMConfig(fromURL: configURL).macAddress.string
+  }
+}
+
+fileprivate extension VMStorageLocal {
+  func hasVMsWithMACAddress(macAddress: String) throws -> Bool {
+    try list().contains { try $1.macAddress() == macAddress }
   }
 }

Sources/tart/Commands/Create.swift

@@ -9,27 +9,50 @@ struct Create: AsyncParsableCommand {
   @Argument(help: "VM name")
   var name: String
 
-  @Option(help: ArgumentHelp("Path to the IPSW file (or \"latest\") to fetch the latest appropriate IPSW", valueName: "path")) 
+  @Option(help: ArgumentHelp("create a macOS VM using path to the IPSW file (or \"latest\") to fetch the latest appropriate IPSW", valueName: "path"))
   var fromIPSW: String?
 
+  @Flag(help: "create a Linux VM")
+  var linux: Bool = false
+
   @Option(help: ArgumentHelp("Disk size in Gb")) 
-  var diskSize: UInt8 = 32
+  var diskSize: UInt16 = 50
 
   func validate() throws {
-    if fromIPSW == nil {
-      throw ValidationError("Please specify a --from-ipsw option!")
+    if fromIPSW == nil && !linux {
+      throw ValidationError("Please specify either a --from-ipsw or --linux option!")
     }
   }
 
   func run() async throws {
     do {
-      let vmDir = try VMStorageLocal().create(name)
+      let tmpVMDir = try VMDirectory.temporary()
 
-      if fromIPSW! == "latest" {
-        _ = try await VM(vmDir: vmDir, ipswURL: nil, diskSizeGB: diskSize)
-      } else {
-        _ = try await VM(vmDir: vmDir, ipswURL: URL(fileURLWithPath: fromIPSW!), diskSizeGB: diskSize)
-      }
+      // Lock the temporary VM directory to prevent it's garbage collection
+      let tmpVMDirLock = try FileLock(lockURL: tmpVMDir.baseURL)
+      try tmpVMDirLock.lock()
+
+      try await withTaskCancellationHandler(operation: {
+        if let fromIPSW = fromIPSW {
+          if fromIPSW == "latest" {
+            _ = try await VM(vmDir: tmpVMDir, ipswURL: nil, diskSizeGB: diskSize)
+          } else {
+            _ = try await VM(vmDir: tmpVMDir, ipswURL: URL(fileURLWithPath: fromIPSW), diskSizeGB: diskSize)
+          }
+        }
+
+        if linux {
+          if #available(macOS 13, *) {
+            _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
+          } else {
+            throw UnsupportedOSError("Linux VMs", "are")
+          }
+        }
+
+        try VMStorageLocal().move(name, from: tmpVMDir)
+      }, onCancel: {
+        try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+      })
 
       Foundation.exit(0)
     } catch {

Sources/tart/Commands/IP.swift

@@ -16,14 +16,21 @@ struct IP: AsyncParsableCommand {
     do {
       let vmDir = try VMStorageLocal().open(name)
       let vmConfig = try VMConfig.init(fromURL: vmDir.configURL)
+      let vmMACAddress = MACAddress(fromString: vmConfig.macAddress.string)!
 
-      guard let ip = try await resolveIP(vmConfig, secondsToWait: wait) else {
+      guard let ipViaDHCP = try await IP.resolveIP(vmMACAddress, secondsToWait: wait) else {
         print("no IP address found, is your VM running?")
 
         Foundation.exit(1)
       }
 
-      print(ip)
+      if let ipViaARP = try ARPCache.ResolveMACAddress(macAddress: vmMACAddress), ipViaARP != ipViaDHCP {
+        fputs("WARNING: DHCP lease and ARP cache entries for MAC address \(vmMACAddress) differ: "
+          + "got \(ipViaDHCP) and \(ipViaARP) respectively, consider reporting this case to"
+          + " https://github.com/cirruslabs/tart/issues/172\n", stderr)
+      }
+
+      print(ipViaDHCP)
 
       Foundation.exit(0)
     } catch {
@@ -33,12 +40,11 @@ struct IP: AsyncParsableCommand {
     }
   }
 
-  private func resolveIP(_ config: VMConfig, secondsToWait: UInt16) async throws -> IPv4Address? {
+  static public func resolveIP(_ vmMACAddress: MACAddress, secondsToWait: UInt16) async throws -> IPv4Address? {
     let waitUntil = Calendar.current.date(byAdding: .second, value: Int(secondsToWait), to: Date.now)!
-    let vmMacAddress = MACAddress(fromString: config.macAddress.string)!
 
     repeat {
-      if let ip = try ARPCache.ResolveMACAddress(macAddress: vmMacAddress) {
+      if let ip = try Leases().resolveMACAddress(macAddress: vmMACAddress) {
         return ip
       }
 

Sources/tart/Commands/List.swift

@@ -7,10 +7,10 @@ struct List: AsyncParsableCommand {
 
   func run() async throws {
     do {
-      print("Name\tSource")
+      print("Source\tName")
 
       displayTable("local", try VMStorageLocal().list())
-      displayTable("oci", try VMStorageOCI().list())
+      displayTable("oci", try VMStorageOCI().list().map { (name, vmDir, _) in (name, vmDir) })
 
       Foundation.exit(0)
     } catch {
@@ -21,7 +21,7 @@ struct List: AsyncParsableCommand {
   }
 
   private func displayTable(_ source: String, _ vms: [(String, VMDirectory)]) {
-    for (name, _) in vms {
+    for (name, _) in vms.sorted(by: { left, right in left.0 < right.0 }) {
       print("\(source)\t\(name)")
     }
   }

Sources/tart/Commands/Login.swift

@@ -8,11 +8,52 @@ struct Login: AsyncParsableCommand {
   @Argument(help: "host")
   var host: String
 
+  @Option(help: "username")
+  var username: String?
+
+  @Flag(help: "password-stdin")
+  var passwordStdin: Bool = false
+
+  @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
+  var insecure: Bool = false
+
+  func validate() throws {
+    let usernameProvided = username != nil
+    let passwordProvided = passwordStdin
+
+    if usernameProvided != passwordProvided {
+      throw ValidationError("both --username and --password-stdin are required")
+    }
+  }
+
   func run() async throws {
     do {
-      let (user, password) = try Credentials.retrieveStdin()
+      var user: String
+      var password: String
 
-      try Credentials.store(host: host, user: user, password: password)
+      if let username = username {
+        user = username
+
+        let passwordData = FileHandle.standardInput.readDataToEndOfFile()
+        password = String(decoding: passwordData, as: UTF8.self)
+      } else {
+        (user, password) = try StdinCredentials.retrieve()
+      }
+      let credentialsProvider = DictionaryCredentialsProvider([
+        host: (user, password)
+      ])
+
+      do {
+        let registry = try Registry(host: host, namespace: "", insecure: insecure,
+          credentialsProviders: [credentialsProvider])
+        try await registry.ping()
+      } catch {
+        print("invalid credentials: \(error)")
+
+        Foundation.exit(1)
+      }
+
+      try KeychainCredentialsProvider().store(host: host, user: user, password: password)
 
       Foundation.exit(0)
     } catch {
@@ -22,3 +63,19 @@ struct Login: AsyncParsableCommand {
     }
   }
 }
+
+fileprivate class DictionaryCredentialsProvider: CredentialsProvider {
+  var credentials: Dictionary<String, (String, String)>
+
+  init(_ credentials: Dictionary<String, (String, String)>) {
+    self.credentials = credentials
+  }
+
+  func retrieve(host: String) throws -> (String, String)? {
+    credentials[host]
+  }
+
+  func store(host: String, user: String, password: String) throws {
+    credentials[host] = (user, password)
+  }
+}

Sources/tart/Commands/Prune.swift

@@ -0,0 +1,108 @@
+import ArgumentParser
+import Dispatch
+import SwiftUI
+import SwiftDate
+
+struct Prune: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Prune OCI and IPSW caches")
+
+  @Option(help: ArgumentHelp("Remove cache entries 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"))
+  var cacheBudget: UInt?
+
+  @Flag(help: .hidden)
+  var gc: Bool = false
+
+  func validate() throws {
+    if olderThan == nil && cacheBudget == nil && !gc {
+      throw ValidationError("at least one pruning criteria must be specified")
+    }
+  }
+
+  func run() async throws {
+    do {
+      if gc {
+        try VMStorageOCI().gc()
+      }
+
+      // Clean up cache entries based on last accessed date
+      if let olderThan = olderThan {
+        let olderThanInterval = Int(exactly: olderThan)!.days.timeInterval
+        let olderThanDate = Date().addingTimeInterval(olderThanInterval)
+
+        try Prune.pruneOlderThan(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)
+      }
+
+      Foundation.exit(0)
+    } catch {
+      print(error)
+
+      Foundation.exit(1)
+    }
+  }
+
+  static func pruneOlderThan(olderThanDate: Date) throws {
+    let prunableStorages: [PrunableStorage] = [VMStorageOCI(), try IPSWCache()]
+    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()]
+    let prunables: [Prunable] = try prunableStorages
+            .flatMap { try $0.prunables() }
+            .sorted { try $0.accessDate() < $1.accessDate() }
+
+    let cacheUsedBytes = try prunables.map { try $0.sizeBytes() }.reduce(0, +)
+    var cacheReclaimedBytes: Int = 0
+
+    var it = prunables.makeIterator()
+
+    while (cacheUsedBytes - cacheReclaimedBytes) > cacheBudgetBytes {
+      guard let prunable = it.next() else {
+        break
+      }
+
+      cacheReclaimedBytes -= try prunable.sizeBytes()
+      try prunable.delete()
+    }
+  }
+
+  static func pruneReclaim(reclaimBytes: UInt64) throws {
+    let prunableStorages: [PrunableStorage] = [VMStorageOCI(), try IPSWCache()]
+    let prunables: [Prunable] = try prunableStorages
+            .flatMap { try $0.prunables() }
+            .sorted { try $0.accessDate() < $1.accessDate() }
+
+    // Does it even make sense to start?
+    let cacheUsedBytes = try prunables.map { try $0.sizeBytes() }.reduce(0, +)
+    if cacheUsedBytes < reclaimBytes {
+      return
+    }
+
+    var cacheReclaimedBytes: Int = 0
+
+    var it = prunables.makeIterator()
+
+    while cacheReclaimedBytes <= reclaimBytes {
+      guard let prunable = it.next() else {
+        break
+      }
+
+      cacheReclaimedBytes += try prunable.sizeBytes()
+      try prunable.delete()
+    }
+  }
+}

Sources/tart/Commands/Pull.swift

@@ -8,10 +8,21 @@ struct Pull: AsyncParsableCommand {
   @Argument(help: "remote VM name")
   var remoteName: String
 
+  @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
+  var insecure: Bool = false
+
   func run() async throws {
     do {
+      // Be more liberal when accepting local image as argument,
+      // see https://github.com/cirruslabs/tart/issues/36
+      if VMStorageLocal().exists(remoteName) {
+        print("\"\(remoteName)\" is a local image, nothing to pull here!")
+
+        Foundation.exit(0)
+      }
+
       let remoteName = try RemoteName(remoteName)
-      let registry = try Registry(host: remoteName.host, namespace: remoteName.namespace)
+      let registry = try Registry(host: remoteName.host, namespace: remoteName.namespace, insecure: insecure)
 
       defaultLogger.appendNewLine("pulling \(remoteName)...")
 

Sources/tart/Commands/Push.swift

@@ -12,6 +12,21 @@ struct Push: AsyncParsableCommand {
   @Argument(help: "remote VM name(s)")
   var remoteNames: [String]
 
+  @Flag(help: "connect to the OCI registry via insecure HTTP protocol")
+  var insecure: Bool = false
+
+  @Option(help: ArgumentHelp("chunk size in MB if registry supports chunked uploads",
+    discussion: """
+                By default monolithic method is used for uploading blobs to the registry but some registries support a more efficient chunked method.
+                For example, AWS Elastic Container Registry supports only chunks larger than 5MB but GitHub Container Registry supports only chunks smaller than 4MB. Google Container Registry on the other hand doesn't support chunked uploads at all.
+                Please refer to the documentation of your particular registry in order to see if this option is suitable for you and what's the recommended chunk size.
+                """))
+  var chunkSize: Int = 0
+
+  @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
+
   func run() async throws {
     do {
       let localVMDir = try VMStorageLocal().open(localName)
@@ -33,14 +48,27 @@ struct Push: AsyncParsableCommand {
 
       // Push VM
       for (registryIdentifier, remoteNamesForRegistry) in registryGroups {
-        let registry = try Registry(host: registryIdentifier.host, namespace: registryIdentifier.namespace)
+        let registry = try Registry(host: registryIdentifier.host, namespace: registryIdentifier.namespace,
+          insecure: insecure)
 
-        let listOfTagsAndDigests = "{" + remoteNamesForRegistry.map{$0.fullyQualifiedReference }
-                .joined(separator: ",") + "}"
         defaultLogger.appendNewLine("pushing \(localName) to "
-          + "\(registryIdentifier.host)/\(registryIdentifier.namespace)\(listOfTagsAndDigests)...")
+          + "\(registryIdentifier.host)/\(registryIdentifier.namespace)\(remoteNamesForRegistry.referenceNames())...")
 
-        try await localVMDir.pushToRegistry(registry: registry, references: remoteNamesForRegistry.map{ $0.reference })
+        let pushedRemoteName = try await localVMDir.pushToRegistry(
+          registry: registry, 
+          references: remoteNamesForRegistry.map{ $0.reference.value }, 
+          chunkSizeMb: chunkSize
+        )
+
+        // Populate the local cache (if requested)
+        if populateCache {
+          let ociStorage = VMStorageOCI()
+          let expectedPushedVMDir = try ociStorage.create(pushedRemoteName)
+          try localVMDir.clone(to: expectedPushedVMDir, generateMAC: false)
+          for remoteName in remoteNamesForRegistry {
+            try ociStorage.link(from: remoteName, to: pushedRemoteName)
+          }
+        }
       }
 
       Foundation.exit(0)
@@ -51,3 +79,15 @@ struct Push: AsyncParsableCommand {
     }
   }
 }
+
+extension Collection where Element == RemoteName {
+  func referenceNames() -> String {
+    let references = self.map{ $0.reference.fullyQualified }
+
+    switch count {
+    case 0: return "∅"
+    case 1: return references.first!
+    default: return "{" + references.joined(separator: ",") + "}"
+    }
+  }
+}

Sources/tart/Commands/Run.swift

@@ -5,62 +5,220 @@ import Virtualization
 
 var vm: VM?
 
+struct IPNotFound: Error {
+}
+
 struct Run: AsyncParsableCommand {
   static var configuration = CommandConfiguration(abstract: "Run a VM")
 
   @Argument(help: "VM name")
   var name: String
 
-  @Flag var noGraphics: Bool = false
+  @Flag(help: ArgumentHelp(
+          "Don't open a UI window.",
+          discussion: "Useful for integrating Tart VMs into other tools.\nUse `tart ip` in order to get an IP for SSHing or VNCing into the VM.")) 
+  var noGraphics: Bool = false
+
+  @Flag(help: "Boot into recovery mode") 
+  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."))
+  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."))
+  var vncExperimental: Bool = false
+
+  @Flag var withSoftnet: Bool = false
+
+  @Option(help: ArgumentHelp("""
+    Additional disk attachments with an optional read-only specifier\n(e.g. --disk=\"disk.bin\" --disk=\"ubuntu.iso:ro\")
+    """, discussion: """
+    Learn how to create a disk image using Disk Utility here:
+    https://support.apple.com/en-gb/guide/disk-utility/dskutl11888/mac
+    """, valueName: "path[:ro]"))
+  var disk: [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]"))
+  var dir: [String] = []
+
+  func validate() throws {
+    if vnc && vncExperimental {
+      throw ValidationError("--vnc and --vnc-experimental are mutually exclusive")
+    }
+  }
 
   @MainActor
   func run() async throws {
     let vmDir = try VMStorageLocal().open(name)
-    vm = try VM(vmDir: vmDir)
+    vm = try VM(
+      vmDir: vmDir,
+      withSoftnet: withSoftnet,
+      additionalDiskAttachments: additionalDiskAttachments(),
+      directoryShares: directoryShares()
+    )
 
-    Task {
+    let vncImpl: VNC? = try {
+      if vnc {
+        let vmConfig = try VMConfig.init(fromURL: vmDir.configURL)
+        return ScreenSharingVNC(vmConfig: vmConfig)
+      } else if vncExperimental {
+        return FullFledgedVNC(virtualMachine: vm!.virtualMachine)
+      } else {
+        return nil
+      }
+    }()
+
+    let task = Task {
       do {
-        try await vm!.run()
+        if let vncImpl = vncImpl {
+          let vncURL = try await vncImpl.waitForURL()
+
+          if noGraphics || ProcessInfo.processInfo.environment["CI"] != nil {
+            print("VNC server is running at \(vncURL)")
+          } else {
+            print("Opening \(vncURL)...")
+            NSWorkspace.shared.open(vncURL)
+          }
+        }
+
+        try await vm!.run(recovery)
+
+        if let vncImpl = vncImpl {
+          try vncImpl.stop()
+        }
 
         Foundation.exit(0)
       } catch {
-        print(error)
+        if error.localizedDescription.contains("Failed to lock auxiliary storage.") {
+          print("Virtual machine \"\(name)\" is already running!")
+          Foundation.exit(2)
+        }
 
+        print(error)
         Foundation.exit(1)
       }
     }
 
-    if noGraphics {
+    let sigintSrc = DispatchSource.makeSignalSource(signal: SIGINT)
+    sigintSrc.setEventHandler {
+      task.cancel()
+    }
+    sigintSrc.activate()
+
+    if noGraphics || vnc || vncExperimental {
       dispatchMain()
     } else {
-      // UI mumbo-jumbo
-      let nsApp = NSApplication.shared
-      nsApp.setActivationPolicy(.regular)
-      nsApp.activate(ignoringOtherApps: true)
+      runUI()
+    }
+  }
 
-      nsApp.applicationIconImage = NSImage(data: AppIconData)
+  func additionalDiskAttachments() throws -> [VZDiskImageStorageDeviceAttachment] {
+    var result: [VZDiskImageStorageDeviceAttachment] = []
+    let readOnlySuffix = ":ro"
+    let expandedDiskPaths = disk.map { NSString(string:$0).expandingTildeInPath }
 
-      struct MainApp: App {
-        var body: some Scene {
-          WindowGroup(vm!.name) {
-            Group {
-              VMView(vm: vm!).onAppear {
-                NSWindow.allowsAutomaticWindowTabbing = false
-              }
-            }.frame(width: CGFloat(vm!.config.display.width), height: CGFloat(vm!.config.display.height))
-          }.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: {})
-          }
+    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
+        ))
+      }
+    }
+
+    return result
+  }
+
+  func directoryShares() throws -> [DirectoryShare] {
+    var result: [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\"")
         }
       }
 
-      MainApp.main()
+      let (name, path) = (String(splits[0]), String(splits[1]))
+
+      result.append(DirectoryShare(name: name, path: URL(fileURLWithPath: NSString(string: path).expandingTildeInPath), readOnly: readOnly))
+    }
+
+    return result
+  }
+
+  private func runUI() {
+    let nsApp = NSApplication.shared
+    nsApp.setActivationPolicy(.regular)
+    nsApp.activate(ignoringOtherApps: true)
+
+    nsApp.applicationIconImage = NSImage(data: AppIconData)
+
+    struct MainApp: App {
+      var body: some Scene {
+        WindowGroup(vm!.name) {
+          Group {
+            VMView(vm: vm!).onAppear {
+              NSWindow.allowsAutomaticWindowTabbing = false
+            }.onDisappear {
+              NSApplication.shared.terminate(self)
+            }
+          }.frame(width: CGFloat(vm!.config.display.width), height: CGFloat(vm!.config.display.height))
+        }.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() }
+                }
+      }
+    }
+
+    MainApp.main()
+  }
+}
+
+struct AboutTart: View {
+  var body: some View {
+    Button("About Tart") {
+      NSApplication.shared.orderFrontStandardAboutPanel(options: [
+        NSApplication.AboutPanelOptionKey.applicationIcon: NSApplication.shared.applicationIconImage as Any,
+        NSApplication.AboutPanelOptionKey.applicationName: "Tart",
+        NSApplication.AboutPanelOptionKey.applicationVersion: CI.version,
+        NSApplication.AboutPanelOptionKey.credits: try! NSAttributedString(markdown: "https://github.com/cirruslabs/tart"),
+      ])
     }
   }
 }

Sources/tart/Commands/Set.swift

@@ -2,7 +2,7 @@ import ArgumentParser
 import Foundation
 
 struct Set: AsyncParsableCommand {
-  static var configuration = CommandConfiguration(abstract: "Modify VM's configuration")
+  static var configuration = CommandConfiguration(commandName: "set", abstract: "Modify VM's configuration")
 
   @Argument(help: "VM name")
   var name: String
@@ -13,11 +13,11 @@ struct Set: AsyncParsableCommand {
   @Option(help: "VM memory size in megabytes")
   var memory: UInt16?
 
-  @Option(help: "VM display settings in a format of <width>x<height>(x<dpi>)?. For example, 1200x800 or 1200x800x72")
+  @Option(help: "VM display resolution in a format of <width>x<height>. For example, 1200x800")
   var display: VMDisplayConfig?
 
   @Option(help: .hidden)
-  var diskSize: UInt8?
+  var diskSize: UInt16?
 
   func run() async throws {
     do {
@@ -39,9 +39,6 @@ struct Set: AsyncParsableCommand {
         if (display.height > 0) {
           vmConfig.display.height = display.height
         }
-        if (display.dpi > 0) {
-          vmConfig.display.dpi = display.dpi
-        }
       }
 
       try vmConfig.save(toURL: vmDir.configURL)
@@ -66,8 +63,7 @@ extension VMDisplayConfig: ExpressibleByArgument {
     }
     self = VMDisplayConfig(
       width: parts[safe: 0] ?? 0,
-      height: parts[safe: 1] ?? 0,
-      dpi: parts[safe: 2] ?? 0
+      height: parts[safe: 1] ?? 0
     )
   }
 }

Sources/tart/Config.swift

@@ -1,9 +1,52 @@
 import Foundation
 
 struct Config {
-  public static let tartHomeDir: URL = FileManager.default
-          .homeDirectoryForCurrentUser
-          .appendingPathComponent(".tart", isDirectory: true)
+  let tartHomeDir: URL
+  let tartCacheDir: URL
+  let tartTmpDir: URL
 
-  public static let tartCacheDir: URL = tartHomeDir.appendingPathComponent("cache", isDirectory: true)
+  init() throws {
+    var tartHomeDir: URL
+
+    if let customTartHome = ProcessInfo.processInfo.environment["TART_HOME"] {
+      tartHomeDir = URL(fileURLWithPath: customTartHome)
+    } else {
+      tartHomeDir = FileManager.default
+              .homeDirectoryForCurrentUser
+              .appendingPathComponent(".tart", isDirectory: true)
+    }
+    self.tartHomeDir = tartHomeDir
+
+    tartCacheDir = tartHomeDir.appendingPathComponent("cache", isDirectory: true)
+    try FileManager.default.createDirectory(at: tartCacheDir, withIntermediateDirectories: true)
+
+    tartTmpDir = tartHomeDir.appendingPathComponent("tmp", isDirectory: true)
+    try FileManager.default.createDirectory(at: tartTmpDir, withIntermediateDirectories: true)
+  }
+
+  func gc() throws {
+    for entry in try FileManager.default.contentsOfDirectory(at: tartTmpDir,
+        includingPropertiesForKeys: [], options: []) {
+      let lock = try FileLock(lockURL: entry)
+      if try !lock.trylock() {
+        continue
+      }
+
+      try FileManager.default.removeItem(at: entry)
+
+      try lock.unlock()
+    }
+  }
+
+  static func jsonEncoder() -> JSONEncoder {
+    let encoder = JSONEncoder()
+
+    encoder.outputFormatting = [.sortedKeys]
+
+    return encoder
+  }
+
+  static func jsonDecoder() -> JSONDecoder {
+    JSONDecoder()
+  }
 }

Sources/tart/Credentials.swift

@@ -1,64 +0,0 @@
-import Foundation
-
-class Credentials {
-  static func retrieveKeychain(host: String) throws -> (String, String)? {
-    let query: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
-                                kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
-                                kSecAttrServer as String: host,
-                                kSecMatchLimit as String: kSecMatchLimitOne,
-                                kSecReturnAttributes as String: true,
-                                kSecReturnData as String: true,
-                                kSecAttrLabel as String: "Tart Credentials",
-    ]
-
-    var item: CFTypeRef?
-    let status = SecItemCopyMatching(query as CFDictionary, &item)
-
-    if status != errSecSuccess {
-      if status == errSecItemNotFound {
-        return nil
-      }
-
-      throw RegistryError.AuthFailed(why: "Keychain returned unsuccessful status \(status)")
-    }
-
-    guard let item = item as? [String: Any],
-          let user = item[kSecAttrAccount as String] as? String,
-          let passwordData = item[kSecValueData as String] as? Data,
-          let password = String(data: passwordData, encoding: .utf8)
-      else {
-      throw RegistryError.AuthFailed(why: "Keychain item has unexpected format")
-    }
-
-    return (user, password)
-  }
-
-  static func retrieveStdin() throws -> (String, String) {
-    print("User: ", terminator: "")
-    let user = readLine() ?? ""
-
-    let rawPass = getpass("Password: ")
-    let pass = String(cString: rawPass!, encoding: .utf8)!
-
-    return (user, pass)
-  }
-
-  static func store(host: String, user: String, password: String) throws {
-    let attributes: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
-                                     kSecAttrAccount as String: user,
-                                     kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
-                                     kSecAttrServer as String: host,
-                                     kSecValueData as String: password,
-                                     kSecAttrLabel as String: "Tart Credentials",
-    ]
-
-    let status = SecItemAdd(attributes as CFDictionary, nil)
-
-    switch status {
-    case errSecSuccess, errSecDuplicateItem:
-      return
-    default:
-      throw RegistryError.AuthFailed(why: "Keychain returned unsuccessful status \(status)")
-    }
-  }
-}

Sources/tart/Credentials/CredentialsProvider.swift

@@ -0,0 +1,10 @@
+import Foundation
+
+enum CredentialsProviderError: Error {
+    case Failed(message: String)
+}
+
+protocol CredentialsProvider {
+    func retrieve(host: String) throws -> (String, String)?
+    func store(host: String, user: String, password: String) throws
+}

Sources/tart/Credentials/DockerConfigCredentialsProvider.swift

@@ -0,0 +1,88 @@
+import Foundation
+
+class DockerConfigCredentialsProvider: CredentialsProvider {
+  func retrieve(host: String) throws -> (String, String)? {
+    let dockerConfigURL = FileManager.default.homeDirectoryForCurrentUser.appendingPathComponent(".docker").appendingPathComponent("config.json")
+    if !FileManager.default.fileExists(atPath: dockerConfigURL.path) {
+      return nil
+    }
+    let config = try JSONDecoder().decode(DockerConfig.self, from: Data(contentsOf: dockerConfigURL))
+
+    if let credentialsFromAuth = config.auths?[host]?.decodeCredentials() {
+      return credentialsFromAuth
+    }
+    if let helperProgram = config.credHelpers?[host] {
+      return try executeHelper(binaryName: "docker-credential-\(helperProgram)", host: host)
+    }
+
+    return nil
+  }
+
+  private func executeHelper(binaryName: String, host: String) throws -> (String, String)? {
+    guard let executableURL = resolveBinaryPath(binaryName) else {
+      throw CredentialsProviderError.Failed(message: "\(binaryName) not found in PATH")
+    }
+    
+    let process = Process.init()
+    process.executableURL = executableURL
+    process.arguments = ["get"]
+
+    let outPipe = Pipe()
+    let inPipe = Pipe()
+    
+    process.standardOutput = outPipe
+    process.standardError = outPipe
+    process.standardInput = inPipe
+
+    process.launch()
+
+    inPipe.fileHandleForWriting.write("\(host)\n".data(using: .utf8)!)
+    inPipe.fileHandleForWriting.closeFile()
+    
+    process.waitUntilExit()
+
+    if !(process.terminationReason == .exit && process.terminationStatus == 0) {
+      throw CredentialsProviderError.Failed(message: "Docker helper failed!")
+    }
+
+    let getOutput = try JSONDecoder().decode(
+      DockerGetOutput.self, from: outPipe.fileHandleForReading.readDataToEndOfFile()
+    )
+    return (getOutput.Username, getOutput.Secret)
+  }
+
+  func store(host: String, user: String, password: String) throws {
+    throw CredentialsProviderError.Failed(message: "Docker helpers don't support storing!")
+  }
+}
+
+struct DockerConfig: Codable {
+  var auths: Dictionary<String, DockerAuthConfig>? = Dictionary()
+  var credHelpers: Dictionary<String, String>? = Dictionary()
+}
+
+struct DockerAuthConfig: Codable {
+  var auth: String? = nil
+
+  func decodeCredentials() -> (String, String)? {
+    // auth is a base64("username:password")
+    guard let authBase64 = auth else {
+      return nil
+    }
+    guard let data = Data(base64Encoded: authBase64) else {
+      return nil
+    }
+    guard let components = String(data: data, encoding: .utf8)?.components(separatedBy: ":") else {
+      return nil
+    }
+    if components.count != 2 {
+      return nil
+    }
+    return (components[0], components[1])
+  }
+}
+
+struct DockerGetOutput: Codable {
+  var Username: String
+  var Secret: String
+}

Sources/tart/Credentials/KeychainCredentialsProvider.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+class KeychainCredentialsProvider: CredentialsProvider {
+    func retrieve(host: String) throws -> (String, String)? {
+        let query: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
+                                    kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
+                                    kSecAttrServer as String: host,
+                                    kSecMatchLimit as String: kSecMatchLimitOne,
+                                    kSecReturnAttributes as String: true,
+                                    kSecReturnData as String: true,
+                                    kSecAttrLabel as String: "Tart Credentials",
+        ]
+
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+        if status != errSecSuccess {
+            if status == errSecItemNotFound {
+                return nil
+            }
+
+            throw CredentialsProviderError.Failed(message: "Keychain returned unsuccessful status \(status)")
+        }
+
+        guard let item = item as? [String: Any],
+              let user = item[kSecAttrAccount as String] as? String,
+              let passwordData = item[kSecValueData as String] as? Data,
+              let password = String(data: passwordData, encoding: .utf8)
+        else {
+            throw CredentialsProviderError.Failed(message: "Keychain item has unexpected format")
+        }
+
+        return (user, password)
+    }
+
+    func store(host: String, user: String, password: String) throws {
+        let passwordData = password.data(using: .utf8)
+        let key: [String: Any] = [kSecClass as String: kSecClassInternetPassword,
+                                  kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
+                                  kSecAttrServer as String: host,
+                                  kSecAttrLabel as String: "Tart Credentials",
+        ]
+        let value: [String: Any] = [kSecAttrAccount as String: user,
+                                    kSecValueData as String: passwordData,
+        ]
+
+        let status = SecItemCopyMatching(key as CFDictionary, nil)
+
+        switch status {
+        case errSecItemNotFound:
+            let status = SecItemAdd(key.merging(value) { (current, _) in current } as CFDictionary, nil)
+            if status != errSecSuccess {
+              throw CredentialsProviderError.Failed(message: "Keychain failed to add item: \(status.explanation())")
+            }
+        case errSecSuccess:
+            let status = SecItemUpdate(key as CFDictionary, value as CFDictionary)
+            if status != errSecSuccess {
+              throw CredentialsProviderError.Failed(message: "Keychain failed to update item: \(status.explanation())")
+            }
+        default:
+            throw CredentialsProviderError.Failed(message: "Keychain failed to find item: \(status.explanation())")
+        }
+    }
+}
+
+extension OSStatus {
+  func explanation() -> CFString {
+    SecCopyErrorMessageString(self, nil) ?? "Unknown status code \(self)." as CFString
+  }
+}

Sources/tart/Credentials/StdinCredentials.swift

@@ -0,0 +1,31 @@
+import Foundation
+
+enum StdinCredentialsError: Error {
+  case CredentialRequired(which: String)
+  case CredentialTooLong(message: String)
+}
+
+class StdinCredentials {
+  static func retrieve() throws -> (String, String) {
+    let user = try readStdinCredential(name: "username", prompt: "User: ", isSensitive: false)
+    let password = try readStdinCredential(name: "password", prompt: "Password: ", isSensitive: true)
+
+    return (user, password)
+  }
+
+  private static func readStdinCredential(name: String, prompt: String, maxCharacters: Int = 255, 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)
+    }
+
+    let credential = String(cString: rawCredential).trimmingCharacters(in: .newlines)
+
+    if credential.count > maxCharacters {
+      throw StdinCredentialsError.CredentialTooLong(
+        message: "\(name) should contain no more than \(maxCharacters) characters")
+    }
+
+    return credential
+  }
+}

Sources/tart/FileLock.swift

@@ -0,0 +1,48 @@
+import Foundation
+import System
+
+enum FileLockError: Error, Equatable {
+    case Failed(_ message: String)
+    case AlreadyLocked
+}
+
+class FileLock {
+    let url: URL
+    let fd: Int32
+
+    init(lockURL: URL) throws {
+        url = lockURL
+        fd = open(lockURL.path, 0)
+    }
+
+    deinit {
+        close(fd)
+    }
+
+    func trylock() throws -> Bool {
+        try flockWrapper(LOCK_EX | LOCK_NB)
+    }
+
+    func lock() throws {
+        _ = try flockWrapper(LOCK_EX)
+    }
+
+    func unlock() throws {
+        _ = try flockWrapper(LOCK_UN)
+    }
+
+    func flockWrapper(_ operation: Int32) throws -> Bool {
+        let ret = flock(fd, operation)
+        if ret != 0 {
+            let details = Errno(rawValue: CInt(errno))
+
+            if (operation & LOCK_NB) != 0 && details == .wouldBlock {
+                return false
+            }
+
+            throw FileLockError.Failed("failed to lock \(url): \(details)")
+        }
+
+        return true
+    }
+}

Sources/tart/IPSWCache.swift

@@ -0,0 +1,20 @@
+import Foundation
+import Virtualization
+
+class IPSWCache: PrunableStorage {
+  let baseURL: URL
+
+  init() throws {
+    baseURL = try Config().tartCacheDir.appendingPathComponent("IPSWs", isDirectory: true)
+    try FileManager.default.createDirectory(at: baseURL, withIntermediateDirectories: true)
+  }
+
+  func locationFor(image: VZMacOSRestoreImage) -> URL {
+    baseURL.appendingPathComponent("\(image.buildVersion).ipsw", isDirectory: false)
+  }
+
+  func prunables() throws -> [Prunable] {
+    try FileManager.default.contentsOfDirectory(at: baseURL, includingPropertiesForKeys: nil)
+            .filter { $0.lastPathComponent.hasSuffix(".ipsw")}
+  }
+}

Sources/tart/Logging/ProgressObserver.swift

@@ -3,6 +3,7 @@ import Foundation
 public class ProgressObserver: NSObject {
   @objc var progressToObserve: Progress
   var observation: NSKeyValueObservation?
+  var lastTimeUpdated = Date.now
 
   public init(_ progress: Progress) {
     progressToObserve = progress
@@ -11,7 +12,11 @@ public class ProgressObserver: NSObject {
   func log(_ renderer: Logger) {
     renderer.appendNewLine(ProgressObserver.lineToRender(progressToObserve))
     observation = observe(\.progressToObserve.fractionCompleted) { progress, _ in
-      renderer.updateLastLine(ProgressObserver.lineToRender(self.progressToObserve))
+      let currentTime = Date.now
+      if self.progressToObserve.isFinished || currentTime.timeIntervalSince(self.lastTimeUpdated) >= 1.0 {
+        self.lastTimeUpdated = currentTime
+        renderer.updateLastLine(ProgressObserver.lineToRender(self.progressToObserve))
+      }
     }
   }
 

Sources/tart/MACAddressResolver/ARPCache.swift

@@ -0,0 +1,119 @@
+import Foundation
+import Network
+import Virtualization
+
+struct ARPCommandFailedError: Error, CustomStringConvertible {
+    var terminationReason: Process.TerminationReason
+    var terminationStatus: Int32
+
+    var description: String {
+        var reason: String
+
+        switch terminationReason {
+        case .exit:
+            reason = "exit code \(terminationStatus)"
+        case .uncaughtSignal:
+            reason = "uncaught signal"
+        default:
+            reason = "unknown reason"
+        }
+
+        return "arp command failed: \(reason)"
+    }
+}
+
+struct ARPCommandYieldedInvalidOutputError: Error, CustomStringConvertible {
+    var explanation: String
+
+    var description: String {
+        "arp command yielded invalid output: \(explanation)"
+    }
+}
+
+struct ARPCacheInternalError: Error, CustomStringConvertible {
+    var explanation: String
+
+    var description: String {
+        "ARPCache internal error: \(explanation)"
+    }
+}
+
+struct ARPCache {
+    static func ResolveMACAddress(macAddress: MACAddress, bridgeOnly: Bool = true) throws -> IPv4Address? {
+        let process = Process.init()
+        process.executableURL = URL.init(fileURLWithPath: "/usr/sbin/arp")
+        process.arguments = ["-an"]
+
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = pipe
+        process.standardInput = FileHandle.nullDevice
+
+        try process.run()
+        process.waitUntilExit()
+
+        if !(process.terminationReason == .exit && process.terminationStatus == 0) {
+            throw ARPCommandFailedError(
+                    terminationReason: process.terminationReason,
+                    terminationStatus: process.terminationStatus)
+        }
+
+        guard let rawLines = try pipe.fileHandleForReading.readToEnd() else {
+            throw ARPCommandYieldedInvalidOutputError(explanation: "empty output")
+        }
+        let lines = String(decoding: rawLines, as: UTF8.self)
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+                .components(separatedBy: "\n")
+
+        // Based on https://opensource.apple.com/source/network_cmds/network_cmds-606.40.2/arp.tproj/arp.c.auto.html
+        let regex = try NSRegularExpression(pattern: #"^.* \((?<ip>.*)\) at (?<mac>.*) on (?<interface>.*) .*$"#)
+
+        for line in lines {
+            let nsLineRange = NSRange(line.startIndex..<line.endIndex, in: line)
+
+            guard let match = regex.firstMatch(in: line, range: nsLineRange) else {
+                throw ARPCommandYieldedInvalidOutputError(explanation: "unparseable entry \"\(line)\"")
+            }
+
+            let rawIP = try match.getCaptureGroup(name: "ip", for: line)
+            guard let ip = IPv4Address(rawIP) else {
+                throw ARPCommandYieldedInvalidOutputError(explanation: "failed to parse IPv4 address \(rawIP)")
+            }
+
+            let rawMAC = try match.getCaptureGroup(name: "mac", for: line)
+            if rawMAC == "(incomplete)" {
+                continue
+            }
+            guard let mac = MACAddress(fromString: rawMAC) else {
+                throw ARPCommandYieldedInvalidOutputError(explanation: "failed to parse MAC address \(rawMAC)")
+            }
+
+            let interface = try match.getCaptureGroup(name: "interface", for: line)
+            if bridgeOnly && !interface.starts(with: "bridge") {
+                continue
+            }
+
+            if macAddress == mac {
+                return ip
+            }
+        }
+
+        return nil
+    }
+}
+
+extension NSTextCheckingResult {
+    func getCaptureGroup(name: String, for string: String) throws -> String {
+        let nsRange = self.range(withName: name)
+
+        if nsRange.location == NSNotFound {
+            throw ARPCacheInternalError(explanation: "attempted to retrieve non-existent named capture group \(name)")
+        }
+
+        guard let range = Range.init(nsRange, in: string) else {
+            throw ARPCacheInternalError(explanation: "failed to convert NSRange to Range")
+        }
+
+        return String(string[range])
+    }
+}

Sources/tart/MACAddressResolver/Lease.swift

@@ -0,0 +1,32 @@
+import Network
+
+struct Lease {
+  var mac: MACAddress
+  var ip: IPv4Address
+
+  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 }
+
+    // Parse MAC address
+    let hwAddressSplits = hwAddress.split(separator: ",")
+    if hwAddressSplits.count != 2 {
+      return nil
+    }
+    if let hwAddressProto = Int(hwAddressSplits[0]), hwAddressProto != ARPHRD_ETHER {
+      return nil
+    }
+    guard let mac = MACAddress(fromString: String(hwAddressSplits[1])) else {
+      return nil
+    }
+
+    // Parse IP address
+    guard let ip = IPv4Address(ipAddress) else {
+      return nil
+    }
+
+    self.ip = ip
+    self.mac = mac
+  }
+}

Sources/tart/MACAddressResolver/Leases.swift

@@ -0,0 +1,106 @@
+import Foundation
+import Network
+
+enum LeasesError: Error {
+  case UnexpectedFormat(name: String = "unexpected DHCPD leases file format", message: String, line: Int)
+  case Truncated(name: String = "truncated DHCPD leases file")
+
+  var description: String {
+    switch self {
+
+    case .UnexpectedFormat(name: let name, message: let message, line: let line):
+      return "\(name) on line \(line): \(message)"
+    case .Truncated(name: let name):
+      return "\(name)"
+    }
+  }
+}
+
+class Leases {
+  private let leases: [MACAddress : Lease]
+
+  convenience init() throws {
+    try self.init(URL(fileURLWithPath: "/var/db/dhcpd_leases"))
+  }
+
+  convenience init(_ fromURL: URL) throws {
+    let fileContents = try String(contentsOf: fromURL, encoding: .utf8)
+
+    try self.init(fileContents)
+  }
+
+  init(_ fromString: String) throws {
+    var leases: [MACAddress : Lease] = Dictionary()
+
+    for lease in try Self.retrieveRawLeases(fromString).compactMap({ Lease(fromRawLease: $0) }) {
+      leases[lease.mac] = lease
+    }
+
+    self.leases = leases
+  }
+
+  /// Parse leases from the host cache similarly to the PLCache_read() function found in Apple's Open Source releases.
+  ///
+  /// [1]: https://github.com/apple-opensource/bootp/blob/master/bootplib/NICache.c#L285-L391
+  private static func retrieveRawLeases(_ dhcpdLeasesContents: String) throws -> [[String : String]] {
+    var rawLeases: [[String : String]] = Array()
+
+    enum State {
+      case Nowhere
+      case Start
+      case Body
+      case End
+    }
+    var state = State.Nowhere
+
+    var currentRawLease: [String : String] = Dictionary()
+
+    for (lineNumber, line) in dhcpdLeasesContents.split(separator: "\n").enumerated().map({ ($0 + 1, $1) }) {
+      if line == "{" {
+        // Handle lease block start
+        if state != .Nowhere && state != .End {
+          throw LeasesError.UnexpectedFormat(message: "unexpected lease block start ({)", line: lineNumber)
+        }
+
+        state = .Start
+      } else if line == "}" {
+        // Handle lease block end
+        if state != .Body {
+          throw LeasesError.UnexpectedFormat(message: "unexpected lease block end (})", line: lineNumber)
+        }
+
+        rawLeases.append(currentRawLease)
+        currentRawLease = Dictionary()
+
+        state = .End
+      } else {
+        // Handle lease block contents
+        let lineWithoutTabs = String(line.drop { $0 == " " || $0 == "\t"})
+
+        if lineWithoutTabs.isEmpty {
+          continue
+        }
+
+        let splits = lineWithoutTabs.split(separator: "=", maxSplits: 1)
+        if splits.count != 2 {
+          throw LeasesError.UnexpectedFormat(message: "key-value pair with only a key", line: lineNumber)
+        }
+        let (key, value) = (String(splits[0]), String(splits[1]))
+
+        currentRawLease[key] = value
+
+        state = .Body
+      }
+    }
+
+    if state == .Start || state == .Body {
+      throw LeasesError.Truncated()
+    }
+
+    return rawLeases
+  }
+
+  func resolveMACAddress(macAddress: MACAddress) throws -> IPv4Address? {
+    leases[macAddress]?.ip
+  }
+}

Sources/tart/MACAddressResolver/MACAddress.swift

@@ -1,6 +1,6 @@
 import Foundation
 
-struct MACAddress: Equatable, CustomStringConvertible {
+struct MACAddress: Equatable, Hashable, CustomStringConvertible {
   var mac: [UInt8] = Array(repeating: 0, count: 6)
 
   init?(fromString: String) {
@@ -16,6 +16,6 @@ struct MACAddress: Equatable, CustomStringConvertible {
   }
 
   var description: String {
-    return String(format: "%02x:%02x:%02x:%02x:%02x:%02x", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5])
+    String(format: "%02x:%02x:%02x:%02x:%02x:%02x", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5])
   }
 }

Sources/tart/OCI/Authentication.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+protocol Authentication {
+  func header() -> (String, String)
+  func isValid() -> Bool
+}
+
+struct BasicAuthentication: Authentication {
+  let user: String
+  let password: String
+
+  func header() -> (String, String) {
+    let creds = Data("\(user):\(password)".utf8).base64EncodedString()
+
+    return ("Authorization", "Basic \(creds)")
+  }
+
+  func isValid() -> Bool {
+    true
+  }
+}

Sources/tart/OCI/Manifest.swift

@@ -3,26 +3,70 @@ import Foundation
 let ociManifestMediaType = "application/vnd.oci.image.manifest.v1+json"
 let ociConfigMediaType = "application/vnd.oci.image.config.v1+json"
 
-struct OCIManifest: Encodable, Decodable {
+// Annotations
+let uncompressedDiskSizeAnnotation = "org.cirruslabs.tart.uncompressed-disk-size"
+
+struct OCIManifest: Codable, Equatable {
   var schemaVersion: Int = 2
   var mediaType: String = ociManifestMediaType
   var config: OCIManifestConfig
   var layers: [OCIManifestLayer] = Array()
+  var annotations: Dictionary<String, String>?
+
+  init(config: OCIManifestConfig, layers: [OCIManifestLayer], uncompressedDiskSize: UInt64? = nil) {
+    self.config = config
+    self.layers = layers
+
+    if let uncompressedDiskSize = uncompressedDiskSize {
+      annotations = [
+        uncompressedDiskSizeAnnotation: String(uncompressedDiskSize)
+      ]
+    }
+  }
+
+  init(fromJSON: Data) throws {
+    self = try Config.jsonDecoder().decode(Self.self, from: fromJSON)
+  }
+
+  func toJSON() throws -> Data {
+    try Config.jsonEncoder().encode(self)
+  }
+
+  func digest() throws -> String {
+    try Digest.hash(toJSON())
+  }
+
+  func uncompressedDiskSize() -> UInt64? {
+    guard let value = annotations?[uncompressedDiskSizeAnnotation] else {
+      return nil
+    }
+
+    return UInt64(value)
+  }
 }
 
-struct OCIManifestConfig: Encodable, Decodable {
+struct OCIConfig: Codable {
+  var architecture: Architecture = .arm64
+  var os: OS = .darwin
+
+  func toJSON() throws -> Data {
+    try Config.jsonEncoder().encode(self)
+  }
+}
+
+struct OCIManifestConfig: Codable, Equatable {
   var mediaType: String = ociConfigMediaType
   var size: Int
   var digest: String
 }
 
-struct OCIManifestLayer: Encodable, Decodable {
+struct OCIManifestLayer: Codable, Equatable {
   var mediaType: String
   var size: Int
   var digest: String
 }
 
-struct Descriptor {
+struct Descriptor: Equatable {
   var size: Int
   var digest: String
 }

Sources/tart/OCI/Registry.swift

@@ -1,13 +1,33 @@
 import Foundation
+import NIOCore
+import NIOHTTP1
+import AsyncHTTPClient
+import Algorithms
+import NIOPosix
 
 enum RegistryError: Error {
-  case UnexpectedHTTPStatusCode(when: String, code: Int, details: String = "")
+  case UnexpectedHTTPStatusCode(when: String, code: UInt, details: String = "")
   case MissingLocationHeader
   case AuthFailed(why: String, details: String = "")
   case MalformedHeader(why: String)
 }
 
-struct TokenResponse: Decodable {
+extension HTTPClientResponse.Body {
+  func readTextResponse() async throws -> String? {
+    let data = try await readResponse()
+    return String(decoding: data, as: UTF8.self)
+  }
+
+  func readResponse() async throws -> Data {
+    var result = Data()
+    for try await part in self {
+      result.append(Data(buffer: part))
+    }
+    return result
+  }
+}
+
+struct TokenResponse: Decodable, Authentication {
   let defaultIssuedAt = Date()
   let defaultExpiresIn = 60
 
@@ -16,19 +36,20 @@ struct TokenResponse: Decodable {
   var issuedAt: Date?
 
   static func parse(fromData: Data) throws -> Self {
-    let decoder = JSONDecoder()
+    let decoder = Config.jsonDecoder()
 
     decoder.keyDecodingStrategy = .convertFromSnakeCase
 
-    // RFC3339 date formatter from Apple's documentation[1]
-    //
-    // [1]: https://developer.apple.com/documentation/foundation/dateformatter
-    let dateFormatter = DateFormatter()
-    dateFormatter.locale = Locale(identifier: "en_US_POSIX")
-    dateFormatter.dateFormat = "yyyy-MM-dd'T'HH:mm:ssZZZZZ"
+    let dateFormatter = ISO8601DateFormatter()
+    dateFormatter.formatOptions = [.withInternetDateTime]
     dateFormatter.timeZone = TimeZone(secondsFromGMT: 0)
 
-    decoder.dateDecodingStrategy = .formatted(dateFormatter)
+    decoder.dateDecodingStrategy = .custom { decoder in
+      let container = try decoder.singleValueContainer()
+      let dateString = try container.decode(String.self)
+
+      return dateFormatter.date(from: dateString) ?? Date()
+    }
 
     return try decoder.decode(TokenResponse.self, from: fromData)
   }
@@ -46,61 +67,90 @@ struct TokenResponse: Decodable {
       (issuedAt ?? defaultIssuedAt) + TimeInterval(expiresIn ?? defaultExpiresIn)
     }
   }
-  
-  var isValid: Bool {
-    get {
-      Date() < tokenExpiresAt
-    }
+
+  func header() -> (String, String) {
+    ("Authorization", "Bearer \(token)")
+  }
+
+  func isValid() -> Bool {
+    Date() < tokenExpiresAt
   }
 }
 
 class Registry {
-  var baseURL: URL
-  var namespace: String
+  private let httpClient = HTTPClient(
+    eventLoopGroupProvider: .shared(MultiThreadedEventLoopGroup(numberOfThreads: 1))
+  )
 
-  var currentAuthToken: TokenResponse? = nil
-
-  init(host: String, namespace: String) throws {
-    var baseURLComponents = URLComponents()
-    baseURLComponents.scheme = "https"
-    baseURLComponents.host = host
-    baseURLComponents.path = "/v2/"
-
-    baseURL = baseURLComponents.url!
-    self.namespace = namespace
+  deinit {
+    try! httpClient.syncShutdown()
   }
 
-  func pushManifest(reference: String, config: Descriptor, layers: [OCIManifestLayer]) async throws -> String {
-    let manifest = OCIManifest(config: OCIManifestConfig(size: config.size, digest: config.digest),
-      layers: layers)
-    let manifestJSON = try JSONEncoder().encode(manifest)
+  let baseURL: URL
+  let namespace: String
+  let credentialsProviders: [CredentialsProvider]
 
-    let (responseData, response) = try await endpointRequest("PUT", "\(namespace)/manifests/\(reference)",
+  var currentAuthToken: Authentication? = nil
+
+  init(urlComponents: URLComponents,
+       namespace: String,
+       credentialsProviders: [CredentialsProvider] = [DockerConfigCredentialsProvider(), KeychainCredentialsProvider()]
+  ) throws {
+    baseURL = urlComponents.url!
+    self.namespace = namespace
+    self.credentialsProviders = credentialsProviders
+  }
+
+  convenience init(
+    host: String,
+    namespace: String,
+    insecure: Bool = false,
+    credentialsProviders: [CredentialsProvider] = [DockerConfigCredentialsProvider(), KeychainCredentialsProvider()]
+  ) throws {
+    let proto = insecure ? "http" : "https"
+    let baseURLComponents = URLComponents(string: proto + "://" + host + "/v2/")!
+
+    try self.init(urlComponents: baseURLComponents, namespace: namespace, credentialsProviders: credentialsProviders)
+  }
+
+  func ping() async throws {
+    let response = try await endpointRequest(.GET, "/v2/")
+    if response.status != .ok {
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "doing ping", code: response.status.code)
+    }
+  }
+
+  func pushManifest(reference: String, manifest: OCIManifest) async throws -> String {
+    let manifestJSON = try manifest.toJSON()
+
+    let response = try await endpointRequest(.PUT, "\(namespace)/manifests/\(reference)",
       headers: ["Content-Type": manifest.mediaType],
       body: manifestJSON)
-    if response.statusCode != 201 {
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing manifest", code: response.statusCode,
-        details: String(decoding: responseData, as: UTF8.self))
+    if response.status != .created {
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing manifest", code: response.status.code,
+        details: try await response.body.readTextResponse() ?? "")
     }
 
     return Digest.hash(manifestJSON)
   }
 
   public func pullManifest(reference: String) async throws -> (OCIManifest, Data) {
-    let (responseData, response) = try await endpointRequest("GET", "\(namespace)/manifests/\(reference)",
+    let response = try await endpointRequest(.GET, "\(namespace)/manifests/\(reference)",
       headers: ["Accept": ociManifestMediaType])
-    if response.statusCode != 200 {
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling manifest", code: response.statusCode,
-        details: String(decoding: responseData, as: UTF8.self))
+    if response.status != .ok {
+      let body = try await response.body.readTextResponse()
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling manifest", code: response.status.code,
+        details: body ?? "")
     }
 
-    let manifest = try JSONDecoder().decode(OCIManifest.self, from: responseData)
+    let manifestData = try await response.body.readResponse()
+    let manifest = try OCIManifest(fromJSON: manifestData)
 
-    return (manifest, responseData)
+    return (manifest, manifestData)
   }
 
-  private func uploadLocationFromResponse(response: HTTPURLResponse) throws -> URLComponents {
-    guard let uploadLocationRaw = response.value(forHTTPHeaderField: "Location") else {
+  private func uploadLocationFromResponse(_ response: HTTPClientResponse) throws -> URLComponents {
+    guard let uploadLocationRaw = response.headers.first(name: "Location") else {
       throw RegistryError.MissingLocationHeader
     }
 
@@ -111,56 +161,91 @@ class Registry {
     return URLComponents(url: uploadLocation.absolutize(baseURL), resolvingAgainstBaseURL: true)!
   }
 
-  public func pushBlob(fromData: Data, chunkSize: Int = 5 * 1024 * 1024) async throws -> String {
+  public func pushBlob(fromData: Data, chunkSizeMb: Int = 0) async throws -> String {
     // Initiate a blob upload
-    let (postData, postResponse) = try await endpointRequest("POST", "\(namespace)/blobs/uploads/",
+    let postResponse = try await endpointRequest(.POST, "\(namespace)/blobs/uploads/",
       headers: ["Content-Length": "0"])
-    if postResponse.statusCode != 202 {
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (POST)", code: postResponse.statusCode,
-        details: String(decoding: postData, as: UTF8.self))
+    if postResponse.status != .accepted {
+      let body = try await postResponse.body.readTextResponse()
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (POST)", code: postResponse.status.code,
+        details: body ?? "")
     }
 
     // Figure out where to upload the blob
-    let uploadLocation = try uploadLocationFromResponse(response: postResponse)
-
-    // Upload the blob
-    let headers = [
-      "Content-Length": "\(fromData.count)",
-      "Content-Type": "application/octet-stream",
-    ]
+    var uploadLocation = try uploadLocationFromResponse(postResponse)
 
     let digest = Digest.hash(fromData)
-    let parameters = [
-      "digest": digest,
-    ]
-
-    let (putData, putResponse) = try await rawRequest("PUT", uploadLocation, headers: headers, parameters: parameters,
-      body: fromData)
-    if putResponse.statusCode != 201 {
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (PUT)", code: putResponse.statusCode,
-        details: String(decoding: putData, as: UTF8.self))
+    
+    if chunkSizeMb == 0 {
+      // monolithic upload
+      let response = try await rawRequest(
+        .PUT,
+        uploadLocation,
+        headers: [
+          "Content-Type": "application/octet-stream",
+        ],
+        parameters: ["digest": digest],
+        body: fromData
+      )
+      if response.status != .created {
+        let body = try await response.body.readTextResponse()
+        throw RegistryError.UnexpectedHTTPStatusCode(when: "pushing blob (PUT) to \(uploadLocation)",
+          code: response.status.code, details: body ?? "")
+      }
+      return digest
     }
 
+    // chunked upload
+    var uploadedBytes = 0
+    let chunks = fromData.chunks(ofCount: chunkSizeMb == 0 ? fromData.count : chunkSizeMb * 1_000_000)
+    for (index, chunk) in chunks.enumerated() {
+      let lastChunk = index == (chunks.count - 1)
+      let response = try await rawRequest(
+        lastChunk ? .PUT : .PATCH, 
+        uploadLocation,
+        headers: [
+          "Content-Type": "application/octet-stream",
+          "Content-Range": "\(uploadedBytes)-\(uploadedBytes + chunk.count - 1)",
+        ],
+        parameters: lastChunk ? ["digest": digest] : [:],
+        body: chunk
+      )
+      let expectedStatus: HTTPResponseStatus = lastChunk ? .created : .accepted
+      if response.status != expectedStatus {
+        let body = try await response.body.readTextResponse()
+        throw RegistryError.UnexpectedHTTPStatusCode(when: "streaming blob to \(uploadLocation)",
+          code: response.status.code, details: body ?? "")
+      }
+      uploadedBytes += chunk.count
+      // Update location for the next chunk
+      uploadLocation = try uploadLocationFromResponse(response)
+    }
+    
     return digest
   }
 
-  public func pullBlob(_ digest: String) async throws -> Data {
-    let (putData, putResponse) = try await endpointRequest("GET", "\(namespace)/blobs/\(digest)")
-    if putResponse.statusCode != 200 {
-      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling blob", code: putResponse.statusCode,
-        details: String(decoding: putData, as: UTF8.self))
+  public func pullBlob(_ digest: String, handler: (ByteBuffer) throws -> Void) async throws {
+    let response = try await endpointRequest(.GET, "\(namespace)/blobs/\(digest)")
+    if response.status != .ok {
+      let body = try await response.body.readTextResponse()
+      throw RegistryError.UnexpectedHTTPStatusCode(when: "pulling blob", code: response.status.code,
+        details: body ?? "")
     }
 
-    return putData
+    for try await part in response.body {
+      try Task.checkCancellation()
+
+      try handler(part)
+    }
   }
 
   private func endpointRequest(
-    _ method: String,
+    _ method: HTTPMethod,
     _ endpoint: String,
     headers: Dictionary<String, String> = Dictionary(),
     parameters: Dictionary<String, String> = Dictionary(),
     body: Data? = nil
-  ) async throws -> (Data, HTTPURLResponse) {
+  ) async throws -> HTTPClientResponse {
     let url = URL(string: endpoint, relativeTo: baseURL)!
     let urlComponents = URLComponents(url: url, resolvingAgainstBaseURL: true)!
 
@@ -168,50 +253,63 @@ class Registry {
   }
 
   private func rawRequest(
-    _ method: String,
+    _ method: HTTPMethod,
     _ urlComponents: URLComponents,
     headers: Dictionary<String, String> = Dictionary(),
     parameters: Dictionary<String, String> = Dictionary(),
-    body: Data? = nil
-  ) async throws -> (Data, HTTPURLResponse) {
+    body: Data? = nil,
+    doAuth: Bool = true
+  ) async throws -> HTTPClientResponse {
     var urlComponents = urlComponents
 
-    if urlComponents.queryItems == nil {
+    if urlComponents.queryItems == nil && !parameters.isEmpty {
       urlComponents.queryItems = []
     }
     urlComponents.queryItems?.append(contentsOf: parameters.map { key, value -> URLQueryItem in
       URLQueryItem(name: key, value: value)
     })
 
-    var request = URLRequest(url: urlComponents.url!)
-    request.httpMethod = method
+    var request = HTTPClientRequest(url: urlComponents.string!)
+    request.method = method
     for (key, value) in headers {
-      request.addValue(value, forHTTPHeaderField: key)
+      request.headers.add(name: key, value: value)
+    }
+    if body != nil {
+      request.headers.add(name: "Content-Length", value: "\(body!.count)")
+      request.body = HTTPClientRequest.Body.bytes(body!)
     }
-    request.httpBody = body
 
     // Invalidate token if it has expired
-    if currentAuthToken?.isValid == false {
+    if currentAuthToken?.isValid() == false {
       currentAuthToken = nil
     }
 
-    var (data, response) = try await authAwareRequest(request: request)
+    var response = try await authAwareRequest(request: request)
 
-    if response.statusCode == 401 {
+    if doAuth && response.status == .unauthorized {
       try await auth(response: response)
-      (data, response) = try await authAwareRequest(request: request)
+      response = try await authAwareRequest(request: request)
     }
 
-    return (data, response)
+    return response
   }
 
-  private func auth(response: HTTPURLResponse) async throws {
+  private func auth(response: HTTPClientResponse) async throws {
     // Process WWW-Authenticate header
-    guard let wwwAuthenticateRaw = response.value(forHTTPHeaderField: "WWW-Authenticate") else {
+    guard let wwwAuthenticateRaw = response.headers.first(name: "WWW-Authenticate") else {
       throw RegistryError.AuthFailed(why: "got HTTP 401, but WWW-Authenticate header is missing")
     }
 
     let wwwAuthenticate = try WWWAuthenticate(rawHeaderValue: wwwAuthenticateRaw)
+
+    if wwwAuthenticate.scheme == "Basic" {
+      if let (user, password) = try lookupCredentials(host: baseURL.host!) {
+        currentAuthToken = BasicAuthentication(user: user, password: password)
+      }
+
+      return
+    }
+
     if wwwAuthenticate.scheme != "Bearer" {
       throw RegistryError.AuthFailed(why: "WWW-Authenticate header's authentication scheme "
         + "\"\(wwwAuthenticate.scheme)\" is unsupported, expected \"Bearer\" scheme")
@@ -242,29 +340,39 @@ class Registry {
 
     var headers: Dictionary<String, String> = Dictionary()
 
-    if let (user, password) = try Credentials.retrieveKeychain(host: baseURL.host!) {
+    if let (user, password) = try lookupCredentials(host: baseURL.host!) {
       let encodedCredentials = "\(user):\(password)".data(using: .utf8)?.base64EncodedString()
       headers["Authorization"] = "Basic \(encodedCredentials!)"
     }
 
-    let (tokenResponseRaw, response) = try await rawRequest("GET", authenticateURL, headers: headers)
-    if response.statusCode != 200 {
-      throw RegistryError.AuthFailed(why: "received unexpected HTTP status code \(response.statusCode) "
-        + "while retrieving an authentication token", details: String(decoding: tokenResponseRaw, as: UTF8.self))
+    let response = try await rawRequest(.GET, authenticateURL, headers: headers, doAuth: false)
+    if response.status != .ok {
+      let body = try await response.body.readTextResponse() ?? ""
+      throw RegistryError.AuthFailed(why: "received unexpected HTTP status code \(response.status.code) "
+        + "while retrieving an authentication token", details: body)
     }
 
-    currentAuthToken = try TokenResponse.parse(fromData: tokenResponseRaw)
+    let bodyData = try await response.body.readResponse()
+    currentAuthToken = try TokenResponse.parse(fromData: bodyData)
   }
 
-  private func authAwareRequest(request: URLRequest) async throws -> (Data, HTTPURLResponse) {
+  private func lookupCredentials(host: String) throws -> (String, String)? {
+    for provider in credentialsProviders {
+      if let (user, password) = try provider.retrieve(host: host) {
+        return (user, password)
+      }
+    }
+    return nil
+  }
+
+  private func authAwareRequest(request: HTTPClientRequest) async throws -> HTTPClientResponse {
     var request = request
 
     if let token = currentAuthToken {
-      request.addValue("Bearer \(token.token)", forHTTPHeaderField: "Authorization")
+      let (name, value) = token.header()
+      request.headers.add(name: name, value: value)
     }
 
-    let (responseData, response) = try await URLSession.shared.data(for: request)
-
-    return (responseData, response as! HTTPURLResponse)
+    return try await httpClient.execute(request, deadline: .distantFuture)
   }
 }

Sources/tart/OCI/RemoteName.swift

@@ -1,31 +1,57 @@
 import Foundation
 import Parsing
 
-struct Tail {
-  enum TailType {
+struct Reference: Comparable, Hashable, CustomStringConvertible {
+  enum ReferenceType: Comparable {
     case Tag
     case Digest
   }
 
-  var type: TailType
-  var value: String
-}
+  let type: ReferenceType
+  let value: String
 
-struct RemoteName: Comparable, CustomStringConvertible {
-  var host: String
-  var namespace: String
-  var reference: String = "latest"
-  var fullyQualifiedReference: String {
+  var fullyQualified: String {
     get {
-      if reference.starts(with: "sha256:") {
-        return "@" + reference
+      switch type {
+      case .Tag:
+        return ":" + value
+      case .Digest:
+        return "@" + value
       }
-
-      return ":" + reference
     }
   }
 
-  init(host: String, namespace: String, reference: String) {
+  init(tag: String) {
+    type = .Tag
+    value = tag
+  }
+
+  init(digest: String) {
+    type = .Digest
+    value = digest
+  }
+
+  static func <(lhs: Reference, rhs: Reference) -> Bool {
+    if lhs.type != rhs.type {
+      return lhs.type < rhs.type
+    } else {
+      return lhs.value < rhs.value
+    }
+  }
+
+  var description: String {
+    get {
+      fullyQualified
+    }
+  }
+}
+
+struct RemoteName: Comparable, Hashable, CustomStringConvertible {
+  var host: String
+  var namespace: String
+  var reference: Reference
+
+  init(host: String, namespace: String, reference: Reference) {
     self.host = host
     self.namespace = namespace
     self.reference = reference
@@ -34,6 +60,7 @@ struct RemoteName: Comparable, CustomStringConvertible {
   init(_ name: String) throws {
     let csNormal = [
       UInt8(ascii: "a")...UInt8(ascii: "z"),
+      UInt8(ascii: "A")...UInt8(ascii: "Z"),
       UInt8(ascii: "0")...UInt8(ascii: "9"),
     ].asCharacterSet().union(CharacterSet(charactersIn: "_-."))
 
@@ -57,13 +84,13 @@ struct RemoteName: Comparable, CustomStringConvertible {
           Parse {
             ":"
             csNormal.map {
-              Tail(type: .Tag, value: String($0))
+              Reference(tag: String($0))
             }
           }
           Parse {
             "@sha256:"
             csHex.map {
-              Tail(type: .Digest, value: "sha256:" + String($0))
+              Reference(digest: "sha256:" + String($0))
             }
           }
         }
@@ -75,9 +102,7 @@ struct RemoteName: Comparable, CustomStringConvertible {
 
     host = String(result.0)
     namespace = String(result.1)
-    if let tail = result.2 {
-      reference = tail.value
-    }
+    reference = result.2 ?? Reference(tag: "latest")
   }
 
   static func <(lhs: RemoteName, rhs: RemoteName) -> Bool {
@@ -91,7 +116,7 @@ struct RemoteName: Comparable, CustomStringConvertible {
   }
 
   var description: String {
-    "\(host)/\(namespace)\(fullyQualifiedReference)"
+    "\(host)/\(namespace)\(reference.fullyQualified)"
   }
 }
 

Sources/tart/Passphrase/PassphraseGenerator.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+struct PassphraseGenerator: Sequence {
+    func makeIterator() -> PassphraseIterator {
+        PassphraseIterator()
+    }
+}
+
+struct PassphraseIterator: IteratorProtocol {
+    mutating func next() -> String? {
+        passphrases[Int(arc4random_uniform(UInt32(passphrases.count)))]
+    }
+}

Sources/tart/Platform/Architecture.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+enum Architecture: String, Codable {
+    case arm64
+    case amd64
+}
+
+func CurrentArchitecture() -> Architecture {
+    #if arch(arm64)
+        return .arm64
+    #elseif arch(x86_64)
+        return .amd64
+    #endif
+}

Sources/tart/Platform/Darwin.swift

@@ -0,0 +1,97 @@
+import Virtualization
+
+struct Darwin: Platform {
+    var ecid: VZMacMachineIdentifier
+    var hardwareModel: VZMacHardwareModel
+
+    init(ecid: VZMacMachineIdentifier, hardwareModel: VZMacHardwareModel) {
+        self.ecid = ecid
+        self.hardwareModel = hardwareModel
+    }
+
+    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) -> VZPlatformConfiguration {
+        let result = VZMacPlatformConfiguration()
+
+        result.machineIdentifier = ecid
+        result.auxiliaryStorage = VZMacAuxiliaryStorage(contentsOf: nvramURL)
+        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
+        }
+
+        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
+            )
+        ]
+
+        return result
+    }
+
+    func pointingDevices() -> [VZPointingDeviceConfiguration] {
+        if #available(macOS 13, *) {
+            // Trackpad is only supported starting with macOS Ventura
+            // macOS Monterey will continue using a USB device == .darwin 
+            return [VZMacTrackpadConfiguration(), VZUSBScreenCoordinatePointingDeviceConfiguration()]
+        } else {
+            return [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+        }
+    }
+}

Sources/tart/Platform/Linux.swift

@@ -0,0 +1,37 @@
+import Virtualization
+
+@available(macOS 13, *)
+struct Linux: Platform {
+    func os() -> OS {
+        .linux
+    }
+
+    func bootLoader(nvramURL: URL) throws -> VZBootLoader {
+        let result = VZEFIBootLoader()
+
+        result.variableStore = VZEFIVariableStore(url: nvramURL)
+
+        return result
+    }
+
+    func platform(nvramURL: URL) -> VZPlatformConfiguration {
+        VZGenericPlatformConfiguration()
+    }
+
+    func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration {
+        let result = VZVirtioGraphicsDeviceConfiguration()
+
+        result.scanouts = [
+            VZVirtioGraphicsScanoutConfiguration(
+                    widthInPixels: vmConfig.display.width,
+                    heightInPixels: vmConfig.display.height
+            )
+        ]
+
+        return result
+    }
+
+    func pointingDevices() -> [VZPointingDeviceConfiguration] {
+        [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+    }
+}

Sources/tart/Platform/OS.swift

@@ -0,0 +1,6 @@
+import Virtualization
+
+enum OS: String, Codable {
+    case darwin
+    case linux
+}

Sources/tart/Platform/Platform.swift

@@ -0,0 +1,9 @@
+import Virtualization
+
+protocol Platform: Codable {
+    func os() -> OS
+    func bootLoader(nvramURL: URL) throws -> VZBootLoader
+    func platform(nvramURL: URL) -> VZPlatformConfiguration
+    func graphicsDevice(vmConfig: VMConfig) -> VZGraphicsDeviceConfiguration
+    func pointingDevices() -> [VZPointingDeviceConfiguration]
+}

Sources/tart/Prunable.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+protocol PrunableStorage {
+  func prunables() throws -> [Prunable]
+}
+
+protocol Prunable {
+  func delete() throws
+  func accessDate() throws -> Date
+  func sizeBytes() throws -> Int
+}

Sources/tart/Root.swift

@@ -1,9 +1,11 @@
 import ArgumentParser
+import Foundation
 
 @main
 struct Root: AsyncParsableCommand {
   static var configuration = CommandConfiguration(
     commandName: "tart",
+    version: CI.version,
     subcommands: [
       Create.self,
       Clone.self,
@@ -14,6 +16,36 @@ struct Root: AsyncParsableCommand {
       IP.self,
       Pull.self,
       Push.self,
+      Prune.self,
       Delete.self,
     ])
+
+  public static func main() async throws {
+    // Ensure the default SIGINT handled is disabled,
+    // otherwise there's a race between two handlers
+    signal(SIGINT, SIG_IGN);
+    // Handle cancellation by Ctrl+C ourselves
+    let task = withUnsafeCurrentTask { $0 }!
+    let sigintSrc = DispatchSource.makeSignalSource(signal: SIGINT)
+    sigintSrc.setEventHandler {
+      task.cancel()
+    }
+    sigintSrc.activate()
+
+    // Parse and run command
+    do {
+      var command = try parseAsRoot()
+
+      // Run garbage-collection before each command (shouldn't take too long)
+      try Config().gc()
+
+      if var asyncCommand = command as? AsyncParsableCommand {
+        try await asyncCommand.run()
+      } else {
+        try command.run()
+      }
+    } catch {
+      exit(withError: error)
+    }
+  }
 }

Sources/tart/Softnet.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+enum SoftnetError: Error {
+  case InitializationFailed(why: String)
+}
+
+class Softnet {
+  private let process = Process()
+
+  let vmFD: Int32
+
+  init(vmMACAddress: String) throws {
+    let binaryName = "softnet"
+
+    guard let executableURL = resolveBinaryPath(binaryName) else {
+      throw SoftnetError.InitializationFailed(why: "\(binaryName) not found in PATH")
+    }
+
+    let fds = UnsafeMutablePointer<Int32>.allocate(capacity: MemoryLayout<Int>.stride * 2)
+
+    let ret = socketpair(AF_UNIX, SOCK_DGRAM, 0, fds)
+    if ret != 0 {
+      throw SoftnetError.InitializationFailed(why: "socketpair() failed with exit code \(ret)")
+    }
+
+    vmFD = fds[0]
+    let softnetFD = fds[1]
+
+    try setSocketBuffers(vmFD, 1 * 1024 * 1024);
+    try setSocketBuffers(softnetFD, 1 * 1024 * 1024);
+
+    process.executableURL = executableURL
+    process.arguments = ["--vm-fd", String(STDIN_FILENO), "--vm-mac-address", vmMACAddress]
+    process.standardInput = FileHandle(fileDescriptor: softnetFD, closeOnDealloc: false)
+  }
+
+  func run() throws {
+    try process.run()
+  }
+
+  func stop() throws {
+    process.interrupt()
+    process.waitUntilExit()
+  }
+
+  private func setSocketBuffers(_ fd: Int32, _ sizeBytes: Int) throws {
+    var option_value = sizeBytes
+    let option_len = socklen_t(MemoryLayout<Int>.size)
+
+    var ret = setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &option_value, option_len)
+    if ret != 0 {
+      throw SoftnetError.InitializationFailed(why: "setsockopt(SO_RCVBUF) returned \(ret)")
+    }
+
+    ret = setsockopt(fd, SOL_SOCKET, SO_SNDBUF, &option_value, option_len)
+    if ret != 0 {
+      throw SoftnetError.InitializationFailed(why: "setsockopt(SO_SNDBUF) returned \(ret)")
+    }
+  }
+}

Sources/tart/URL+AccessDate.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+extension URL {
+  func accessDate() throws -> Date {
+    let attrs = try resourceValues(forKeys: [.contentAccessDateKey])
+    return attrs.contentAccessDate!
+  }
+
+  func updateAccessDate(_ accessDate: Date = Date()) throws {
+    let attrs = try resourceValues(forKeys: [.contentAccessDateKey])
+    let modificationDate = attrs.contentAccessDate!
+
+    let times = [accessDate.asTimeval(), modificationDate.asTimeval()]
+    let ret = utimes(path, times)
+    if ret != 0 {
+      throw RuntimeError("utimes(2) failed: \(ret.explanation())")
+    }
+  }
+}
+
+extension Date {
+  func asTimeval() -> timeval {
+    timeval(tv_sec: Int(timeIntervalSince1970), tv_usec: 0)
+  }
+}

Sources/tart/URL+Prunable.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+extension URL: Prunable {
+  func delete() throws {
+    try FileManager.default.removeItem(at: self)
+  }
+
+  func sizeBytes() throws -> Int {
+    try resourceValues(forKeys: [.totalFileAllocatedSizeKey]).totalFileAllocatedSize!
+  }
+}

Sources/tart/Utils.swift

@@ -5,3 +5,20 @@ extension Collection {
     indices.contains(index) ? self[index] : nil
   }
 }
+
+func resolveBinaryPath(_ name: String) -> URL? {
+  guard let path = ProcessInfo.processInfo.environment["PATH"] else {
+    return nil
+  }
+
+  for pathComponent in path.split(separator: ":") {
+    let url = URL(fileURLWithPath: String(pathComponent))
+            .appendingPathComponent(name, isDirectory: false)
+
+    if FileManager.default.fileExists(atPath: url.path) {
+      return url
+    }
+  }
+
+  return nil
+}

Sources/tart/VM+Recovery.swift

@@ -0,0 +1,38 @@
+import Foundation
+import Virtualization
+import Dynamic
+
+// Kudos to @saagarjha's VirtualApple for finding about _VZVirtualMachineStartOptions
+
+extension VZVirtualMachine {
+  @available(macOS 12, *)
+  func start(_ recovery: Bool) async throws {
+    if !recovery {
+      // just use the regular API
+      return try await withCheckedThrowingContinuation { continuation in
+        DispatchQueue.main.async {
+          self.start(completionHandler: { result in
+            continuation.resume(with: result)
+          })
+        }
+      }
+    }
+
+    // use some private stuff only for recovery
+    return try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+      DispatchQueue.main.async {
+        let handler: @convention(block) (_ result: Any?) -> Void = { result in
+          if let error = result as? Error {
+            continuation.resume(throwing: error)
+          } else {
+            continuation.resume(returning: ())
+          }
+        }
+        // dynamic magic
+        let options = Dynamic._VZVirtualMachineStartOptions()
+        options.bootMacOSRecovery = recovery
+        Dynamic(self)._start(withOptions: options, completionHandler: handler)
+      }
+    }
+  }
+}

Sources/tart/VM.swift

@@ -10,6 +10,17 @@ struct NoMainScreenFoundError: Error {
 struct DownloadFailed: Error {
 }
 
+struct UnsupportedOSError: Error, CustomStringConvertible {
+  let description: String
+
+  init(_ what: String, _ plural: String) {
+    description = "error: \(what) \(plural) only supported on hosts running macOS 13.0 (Ventura) or newer"
+  }
+}
+
+struct UnsupportedArchitectureError: Error {
+}
+
 class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   // Virtualization.Framework's virtual machine
   @Published var virtualMachine: VZVirtualMachine
@@ -23,17 +34,32 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   // VM's config
   var config: VMConfig
 
-  init(vmDir: VMDirectory) throws {
-    let auxStorage = VZMacAuxiliaryStorage(contentsOf: vmDir.nvramURL)
+  var softnet: Softnet? = nil
 
+  init(vmDir: VMDirectory,
+       withSoftnet: Bool = false,
+       additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = [],
+       directoryShares: [DirectoryShare] = []
+  ) throws {
     name = vmDir.name
     config = try VMConfig.init(fromURL: vmDir.configURL)
 
-    let configuration = try VM.craftConfiguration(diskURL: vmDir.diskURL, auxStorage: auxStorage, vmConfig: config)
+    if config.arch != CurrentArchitecture() {
+      throw UnsupportedArchitectureError()
+    }
+
+    // Initialize the virtual machine and its configuration
+    if withSoftnet {
+      softnet = try Softnet(vmMACAddress: config.macAddress.string)
+    }
+
+    let configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL,
+      nvramURL: vmDir.nvramURL, vmConfig: config,
+      softnet: softnet, additionalDiskAttachments: additionalDiskAttachments,
+            directoryShares: directoryShares)
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
     super.init()
-
     virtualMachine.delegate = self
   }
 
@@ -45,14 +71,11 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
       }
     }
 
-
-    let ipswCacheFolder = Config.tartCacheDir.appendingPathComponent("IPSWs", isDirectory: true)
-    try FileManager.default.createDirectory(at: ipswCacheFolder, withIntermediateDirectories: true)
-
-    let expectedIPSWLocation = ipswCacheFolder.appendingPathComponent("\(image.buildVersion).ipsw", isDirectory: false)
+    let expectedIPSWLocation = try IPSWCache().locationFor(image: image)
 
     if FileManager.default.fileExists(atPath: expectedIPSWLocation.path) {
       defaultLogger.appendNewLine("Using cached *.ipsw file...")
+      try expectedIPSWLocation.updateAccessDate()
       return expectedIPSWLocation
     }
 
@@ -77,8 +100,23 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     try data.write(to: expectedIPSWLocation, options: [.atomic])
     return expectedIPSWLocation
   }
+  
+  var inFinalState: Bool {
+    get {
+      virtualMachine.state == VZVirtualMachine.State.stopped ||
+        virtualMachine.state == VZVirtualMachine.State.paused ||
+        virtualMachine.state == VZVirtualMachine.State.error
+      
+    }
+  }
 
-  init(vmDir: VMDirectory, ipswURL: URL?, diskSizeGB: UInt8) async throws {
+  init(
+    vmDir: VMDirectory,
+    ipswURL: URL?,
+    diskSizeGB: UInt16,
+    withSoftnet: Bool = false,
+    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment] = []
+  ) async throws {
     let ipswURL = ipswURL != nil ? ipswURL! : try await VM.retrieveLatestIPSW();
 
     // Load the restore image and try to get the requirements
@@ -94,7 +132,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
 
     // Create NVRAM
-    let auxStorage = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)
+    _ = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)
 
     // Create disk
     try vmDir.resizeDisk(diskSizeGB)
@@ -102,18 +140,26 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     name = vmDir.name
     // Create config
     config = VMConfig(
-      hardwareModel: requirements.hardwareModel,
+      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
-    let configuration = try VM.craftConfiguration(diskURL: vmDir.diskURL, auxStorage: auxStorage, vmConfig: config)
+    if withSoftnet {
+      softnet = try Softnet(vmMACAddress: config.macAddress.string)
+    }
+
+    let configuration = try Self.craftConfiguration(diskURL: vmDir.diskURL, nvramURL: vmDir.nvramURL,
+      vmConfig: config, softnet: softnet,
+      additionalDiskAttachments: additionalDiskAttachments,
+      directoryShares: [])
     virtualMachine = VZVirtualMachine(configuration: configuration)
 
     super.init()
-
     virtualMachine.delegate = self
 
     // Run automated installation
@@ -131,66 +177,129 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
     }
   }
 
-  func run() async throws {
-    try await withCheckedThrowingContinuation { continuation in
-      DispatchQueue.main.async {
-        self.virtualMachine.start(completionHandler: { result in
-          continuation.resume(with: result)
-        })
+  @available(macOS 13, *)
+  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16) async throws -> VM {
+    // Create NVRAM
+    _ = try VZEFIVariableStore(creatingVariableStoreAt: vmDir.nvramURL)
+
+    // Create disk
+    try vmDir.resizeDisk(diskSizeGB)
+
+    // Create config
+    let config = VMConfig(platform: Linux(), cpuCountMin: 4, memorySizeMin: 4096 * 1024 * 1024)
+    try config.save(toURL: vmDir.configURL)
+
+    return try VM(vmDir: vmDir)
+  }
+
+  func run(_ recovery: Bool) async throws {
+    if let softnet = softnet {
+      try softnet.run()
+    }
+
+    DispatchQueue.main.sync {
+      Task {
+        if #available(macOS 13, *) {
+          // new API introduced in Ventura
+          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)
+        }
       }
     }
 
-    sema.wait()
+    await withTaskCancellationHandler(operation: {
+      sema.wait()
+    }, onCancel: {
+      sema.signal()
+    })
+
+    if Task.isCancelled {
+      DispatchQueue.main.sync {
+        Task {
+          try await self.virtualMachine.stop()
+        }
+      }
+    }
+
+    if let softnet = softnet {
+      try softnet.stop();
+    }
   }
 
-  static func craftConfiguration(diskURL: URL, auxStorage: VZMacAuxiliaryStorage, vmConfig: VMConfig) throws -> VZVirtualMachineConfiguration {
+  static func craftConfiguration(
+    diskURL: URL,
+    nvramURL: URL,
+    vmConfig: VMConfig,
+    softnet: Softnet? = nil,
+    additionalDiskAttachments: [VZDiskImageStorageDeviceAttachment],
+    directoryShares: [DirectoryShare]
+  ) throws -> VZVirtualMachineConfiguration {
     let configuration = VZVirtualMachineConfiguration()
 
     // Boot loader
-    configuration.bootLoader = VZMacOSBootLoader()
+    configuration.bootLoader = try vmConfig.platform.bootLoader(nvramURL: nvramURL)
 
     // CPU and memory
     configuration.cpuCount = vmConfig.cpuCount
     configuration.memorySize = vmConfig.memorySize
 
     // Platform
-    let platform = VZMacPlatformConfiguration()
-
-    platform.machineIdentifier = vmConfig.ecid
-    platform.auxiliaryStorage = auxStorage
-    platform.hardwareModel = vmConfig.hardwareModel
-
-    configuration.platform = platform
+    configuration.platform = vmConfig.platform.platform(nvramURL: nvramURL)
 
     // Display
-    let graphicsDeviceConfiguration = VZMacGraphicsDeviceConfiguration()
-    graphicsDeviceConfiguration.displays = [
-      VZMacGraphicsDisplayConfiguration(
-        widthInPixels: vmConfig.display.width,
-        heightInPixels: vmConfig.display.height,
-        pixelsPerInch: vmConfig.display.dpi
-      )
-    ]
-    configuration.graphicsDevices = [graphicsDeviceConfiguration]
+    configuration.graphicsDevices = [vmConfig.platform.graphicsDevice(vmConfig: vmConfig)]
+
+    // Audio
+    let soundDeviceConfiguration = VZVirtioSoundDeviceConfiguration()
+    let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
+    inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
+    let outputAudioStreamConfiguration = VZVirtioSoundDeviceOutputStreamConfiguration()
+    outputAudioStreamConfiguration.sink = VZHostAudioOutputStreamSink()
+    soundDeviceConfiguration.streams = [inputAudioStreamConfiguration, outputAudioStreamConfiguration]
+    configuration.audioDevices = [soundDeviceConfiguration]
 
     // Keyboard and mouse
     configuration.keyboards = [VZUSBKeyboardConfiguration()]
-    configuration.pointingDevices = [VZUSBScreenCoordinatePointingDeviceConfiguration()]
+    configuration.pointingDevices = vmConfig.platform.pointingDevices()
 
     // Networking
     let vio = VZVirtioNetworkDeviceConfiguration()
-    vio.attachment = VZNATNetworkDeviceAttachment()
+
+    if let softnet = softnet {
+      let fh = FileHandle.init(fileDescriptor: softnet.vmFD)
+      vio.attachment = VZFileHandleNetworkDeviceAttachment(fileHandle: fh)
+    } else {
+      vio.attachment = VZNATNetworkDeviceAttachment()
+    }
     vio.macAddress = vmConfig.macAddress
     configuration.networkDevices = [vio]
 
     // Storage
-    let attachment = try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)
-    let storage = VZVirtioBlockDeviceConfiguration(attachment: attachment)
-    configuration.storageDevices = [storage]
+    var attachments = [try VZDiskImageStorageDeviceAttachment(url: diskURL, readOnly: false)]
+    attachments.append(contentsOf: additionalDiskAttachments)
+    configuration.storageDevices = attachments.map { VZVirtioBlockDeviceConfiguration(attachment: $0) }
 
     // Entropy
     configuration.entropyDevices = [VZVirtioEntropyDeviceConfiguration()]
 
+    // Directory share
+    if #available(macOS 13, *) {
+      var directories: [String : VZSharedDirectory] = Dictionary()
+      directoryShares.forEach { directories[$0.name] = VZSharedDirectory(url: $0.path, readOnly: $0.readOnly) }
+
+      let automountTag = VZVirtioFileSystemDeviceConfiguration.macOSGuestAutomountTag
+      let sharingDevice = VZVirtioFileSystemDeviceConfiguration(tag: automountTag)
+      sharingDevice.share = VZMultipleDirectoryShare(directories: directories)
+
+      configuration.directorySharingDevices = [sharingDevice]
+    } else if !directoryShares.isEmpty {
+      throw UnsupportedOSError("directory sharing", "is")
+    }
+
     try configuration.validate()
 
     return configuration
@@ -207,7 +316,13 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
   }
 
   func virtualMachine(_ virtualMachine: VZVirtualMachine, networkDevice: VZNetworkDevice, attachmentWasDisconnectedWithError error: Error) {
-    print("virtual machine's network attachment has been disconnected")
+    print("virtual machine's network attachment \(networkDevice) has been disconnected with error: \(error)")
     sema.signal()
   }
 }
+
+struct DirectoryShare {
+  let name: String
+  let path: URL
+  let readOnly: Bool
+}

Sources/tart/VMConfig.swift

@@ -16,43 +16,46 @@ class LessThanMinimalResourcesError: NSObject, LocalizedError {
 
 enum CodingKeys: String, CodingKey {
   case version
-  case ecid
-  case hardwareModel
+  case os
+  case arch
   case cpuCountMin
   case cpuCount
   case memorySizeMin
   case memorySize
   case macAddress
   case display
+
+  // macOS-specific keys
+  case ecid
+  case hardwareModel
 }
 
 struct VMDisplayConfig: Codable {
   var width: Int = 1024
   var height: Int = 768
-  var dpi: Int = 72
 }
 
 struct VMConfig: Codable {
   var version: Int = 1
-  var ecid: VZMacMachineIdentifier
-  var hardwareModel: VZMacHardwareModel
+  var os: OS
+  var arch: Architecture
+  var platform: Platform
   var cpuCountMin: Int
   private(set) var cpuCount: Int
   var memorySizeMin: UInt64
   private(set) var memorySize: UInt64
   var macAddress: VZMACAddress
-  
   var display: VMDisplayConfig = VMDisplayConfig()
 
   init(
-    ecid: VZMacMachineIdentifier = VZMacMachineIdentifier(),
-    hardwareModel: VZMacHardwareModel,
-    cpuCountMin: Int,
-    memorySizeMin: UInt64,
-    macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered()
+          platform: Platform,
+          cpuCountMin: Int,
+          memorySizeMin: UInt64,
+          macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered()
   ) {
-    self.ecid = ecid
-    self.hardwareModel = hardwareModel
+    self.os = platform.os()
+    self.arch = CurrentArchitecture()
+    self.platform = platform
     self.macAddress = macAddress
     self.cpuCountMin = cpuCountMin
     self.memorySizeMin = memorySizeMin
@@ -60,12 +63,16 @@ struct VMConfig: Codable {
     memorySize = memorySizeMin
   }
 
-  init(fromData: Data) throws {
-    self = try JSONDecoder().decode(VMConfig.self, from: fromData)
+  init(fromJSON: Data) throws {
+    self = try Config.jsonDecoder().decode(Self.self, from: fromJSON)
   }
 
   init(fromURL: URL) throws {
-    self = try Self(fromData: try Data(contentsOf: fromURL))
+    self = try Self(fromJSON: try Data(contentsOf: fromURL))
+  }
+
+  func toJSON() throws -> Data {
+    try Config.jsonEncoder().encode(self)
   }
 
   func save(toURL: URL) throws {
@@ -78,29 +85,18 @@ struct VMConfig: Codable {
     let container = try decoder.container(keyedBy: CodingKeys.self)
 
     version = try container.decode(Int.self, forKey: .version)
-
-    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")
+    os = try container.decodeIfPresent(OS.self, forKey: .os) ?? .darwin
+    arch = try container.decodeIfPresent(Architecture.self, forKey: .arch) ?? .arm64
+    switch os {
+    case .darwin:
+      platform = try Darwin(from: decoder)
+    case .linux:
+      if #available(macOS 13, *) {
+        platform = try Linux(from: decoder)
+      } else {
+        throw UnsupportedOSError("Linux VMs", "are")
+      }
     }
-    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
-
     cpuCountMin = try container.decode(Int.self, forKey: .cpuCountMin)
     cpuCount = try container.decode(Int.self, forKey: .cpuCount)
     memorySizeMin = try container.decode(UInt64.self, forKey: .memorySizeMin)
@@ -122,8 +118,9 @@ struct VMConfig: Codable {
     var container = encoder.container(keyedBy: CodingKeys.self)
 
     try container.encode(version, forKey: .version)
-    try container.encode(ecid.dataRepresentation.base64EncodedString(), forKey: .ecid)
-    try container.encode(hardwareModel.dataRepresentation.base64EncodedString(), forKey: .hardwareModel)
+    try container.encode(os, forKey: .os)
+    try container.encode(arch, forKey: .arch)
+    try platform.encode(to: encoder)
     try container.encode(cpuCountMin, forKey: .cpuCountMin)
     try container.encode(cpuCount, forKey: .cpuCount)
     try container.encode(memorySizeMin, forKey: .memorySizeMin)

Sources/tart/VMDirectory+OCI.swift

@@ -4,7 +4,7 @@ import Compression
 enum OCIError: Error {
   case ShouldBeExactlyOneLayer
   case ShouldBeAtLeastOneLayer
-  case FailedToCreateDiskFile
+  case FailedToCreateVmFile
 }
 
 extension VMDirectory {
@@ -31,8 +31,14 @@ extension VMDirectory {
     if configLayers.count != 1 {
       throw OCIError.ShouldBeExactlyOneLayer
     }
-    let configData = try await registry.pullBlob(configLayers.first!.digest)
-    try VMConfig(fromData: configData).save(toURL: configURL)
+    if !FileManager.default.createFile(atPath: configURL.path, contents: nil) {
+      throw OCIError.FailedToCreateVmFile
+    }
+    let configFile = try FileHandle(forWritingTo: configURL)
+    try await registry.pullBlob(configLayers.first!.digest) { buffer in
+      configFile.write(Data(buffer: buffer))
+    }
+    try configFile.close()
 
     // Pull VM's disk layers and decompress them sequentially into a disk file
     let diskLayers = manifest.layers.filter {
@@ -42,7 +48,7 @@ extension VMDirectory {
       throw OCIError.ShouldBeAtLeastOneLayer
     }
     if !FileManager.default.createFile(atPath: diskURL.path, contents: nil) {
-      throw OCIError.FailedToCreateDiskFile
+      throw OCIError.FailedToCreateVmFile
     }
     let disk = try FileHandle(forWritingTo: diskURL)
     let filter = try OutputFilter(.decompress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { data in
@@ -52,18 +58,23 @@ extension VMDirectory {
     }
 
     // Progress
-    let diskCompressedSize: Int64 = Int64(diskLayers.map {$0.size}.reduce(0) {$0 + $1})
+    let diskCompressedSize: Int64 = Int64(diskLayers.map {
+              $0.size
+            }
+            .reduce(0) {
+              $0 + $1
+            })
     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 {
-      let diskData = try await registry.pullBlob(diskLayer.digest)
-      try filter.write(diskData)
-
-      // Progress
-      progress.completedUnitCount += Int64(diskLayer.size)
+      try await registry.pullBlob(diskLayer.digest) { buffer in
+        let data = Data(buffer: buffer)
+        try filter.write(data)
+        progress.completedUnitCount += Int64(data.count)
+      }
     }
     try filter.finalize()
     try disk.close()
@@ -77,64 +88,77 @@ extension VMDirectory {
     if nvramLayers.count != 1 {
       throw OCIError.ShouldBeExactlyOneLayer
     }
-    let nvramData = try await registry.pullBlob(nvramLayers.first!.digest)
-    try nvramData.write(to: nvramURL)
+    if !FileManager.default.createFile(atPath: nvramURL.path, contents: nil) {
+      throw OCIError.FailedToCreateVmFile
+    }
+    let nvram = try FileHandle(forWritingTo: nvramURL)
+    try await registry.pullBlob(nvramLayers.first!.digest) { buffer in
+      nvram.write(Data(buffer: buffer))
+    }
+    try nvram.close()
   }
 
-  func pushToRegistry(registry: Registry, references: [String]) async throws {
+  func pushToRegistry(registry: Registry, references: [String], chunkSizeMb: Int) async throws -> RemoteName {
     var layers = Array<OCIManifestLayer>()
 
     // Read VM's config and push it as blob
     let config = try VMConfig(fromURL: configURL)
     let configJSON = try JSONEncoder().encode(config)
-    let configDigest = try await registry.pushBlob(fromData: configJSON)
+    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))
 
     // Progress
     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 disk = try FileHandle(forReadingFrom: diskURL)
-    let compressingFilter = try InputFilter<Data>(.compress, using: .lz4, bufferCapacity: Self.bufferSizeBytes) { _ in
-      let data = try disk.read(upToCount: Self.bufferSizeBytes)
-      
-      progress.completedUnitCount += Int64(data?.count ?? 0)
+    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 chunk = try compressingFilter.readData(ofLength: Self.layerLimitBytes) {
-      let chunkDigest = try await registry.pushBlob(fromData: chunk)
-      layers.append(OCIManifestLayer(mediaType: Self.diskMediaType, size: chunk.count, digest: chunkDigest))
+    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))
     }
 
     // Read VM's NVRAM and push it as blob
     defaultLogger.appendNewLine("pushing NVRAM...")
 
     let nvram = try FileHandle(forReadingFrom: nvramURL).readToEnd()!
-    let nvramDigest = try await registry.pushBlob(fromData: nvram)
+    let nvramDigest = try await registry.pushBlob(fromData: nvram, chunkSizeMb: chunkSizeMb)
     layers.append(OCIManifestLayer(mediaType: Self.nvramMediaType, size: nvram.count, digest: nvramDigest))
 
     // Craft a stub OCI config for Docker Hub compatibility
-    struct OCIConfig: Encodable, Decodable {
-      var architecture: String = "arm64"
-      var os: String = "darwin"
-    }
-
-    let ociConfigJSON = try JSONEncoder().encode(OCIConfig())
-    let ociConfigDigest = try await registry.pushBlob(fromData: ociConfigJSON)
-    let ociConfigDescriptor = Descriptor(size: ociConfigJSON.count, digest: ociConfigDigest)
+    let ociConfigJSON = try OCIConfig(architecture: config.arch, os: config.os).toJSON()
+    let ociConfigDigest = try await registry.pushBlob(fromData: ociConfigJSON, chunkSizeMb: chunkSizeMb)
+    let manifest = OCIManifest(
+            config: OCIManifestConfig(size: ociConfigJSON.count, digest: ociConfigDigest),
+            layers: layers,
+            uncompressedDiskSize: UInt64(mappedDiskReadOffset)
+    )
 
     // Manifest
     for reference in references {
       defaultLogger.appendNewLine("pushing manifest for \(reference)...")
 
-      _ = try await registry.pushManifest(reference: reference, config: ociConfigDescriptor, layers: layers)
+      _ = try await registry.pushManifest(reference: reference, manifest: manifest)
     }
+
+    let pushedReference = Reference(digest: try manifest.digest())
+    return RemoteName(host: registry.baseURL.host!, namespace: registry.namespace, reference: pushedReference)
   }
 }
 

Sources/tart/VMDirectory.swift

@@ -7,7 +7,7 @@ struct UninitializedVMDirectoryError: Error {
 struct AlreadyInitializedVMDirectoryError: Error {
 }
 
-struct VMDirectory {
+struct VMDirectory: Prunable {
   var baseURL: URL
 
   var configURL: URL {
@@ -20,10 +20,21 @@ struct VMDirectory {
     baseURL.appendingPathComponent("nvram.bin")
   }
 
+  var explicitlyPulledMark: URL {
+    baseURL.appendingPathComponent(".explicitly-pulled")
+  }
+
   var name: String {
     baseURL.lastPathComponent
   }
 
+  static func temporary() throws -> VMDirectory {
+    let tmpDir = try Config().tartTmpDir.appendingPathComponent(UUID().uuidString)
+    try FileManager.default.createDirectory(at: tmpDir, withIntermediateDirectories: false)
+
+    return VMDirectory(baseURL: tmpDir)
+  }
+
   var initialized: Bool {
     FileManager.default.fileExists(atPath: configURL.path) &&
       FileManager.default.fileExists(atPath: diskURL.path) &&
@@ -61,7 +72,7 @@ struct VMDirectory {
     try newVMConfig.save(toURL: to.configURL)
   }
 
-  func resizeDisk(_ sizeGB: UInt8) throws {
+  func resizeDisk(_ sizeGB: UInt16) throws {
     if !FileManager.default.fileExists(atPath: diskURL.path) {
       FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
     }
@@ -70,4 +81,24 @@ struct VMDirectory {
     try diskFileHandle.truncate(atOffset: UInt64(sizeGB) * 1000 * 1000 * 1000)
     try diskFileHandle.close()
   }
+
+  func delete() throws {
+    try FileManager.default.removeItem(at: baseURL)
+  }
+
+  func accessDate() throws -> Date {
+    try baseURL.accessDate()
+  }
+
+  func sizeBytes() throws -> Int {
+    try configURL.sizeBytes() + diskURL.sizeBytes() + nvramURL.sizeBytes()
+  }
+
+  func markExplicitlyPulled() {
+    FileManager.default.createFile(atPath: explicitlyPulledMark.path, contents: nil)
+  }
+
+  func isExplicitlyPulled() -> Bool {
+    FileManager.default.fileExists(atPath: explicitlyPulledMark.path)
+  }
 }

Sources/tart/VMStorageLocal.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 class VMStorageLocal {
-  let baseURL: URL = Config.tartHomeDir.appendingPathComponent("vms", isDirectory: true)
+  let baseURL: URL = try! Config().tartHomeDir.appendingPathComponent("vms", isDirectory: true)
 
   private func vmURL(_ name: String) -> URL {
     baseURL.appendingPathComponent(name, isDirectory: true)
@@ -27,6 +27,11 @@ class VMStorageLocal {
     return vmDir
   }
 
+  func move(_ name: String, from: VMDirectory) throws {
+    _ = try FileManager.default.createDirectory(at: baseURL, withIntermediateDirectories: true)
+    _ = try FileManager.default.replaceItemAt(vmURL(name), withItemAt: from.baseURL)
+  }
+
   func delete(_ name: String) throws {
     try FileManager.default.removeItem(at: vmURL(name))
   }
@@ -36,9 +41,13 @@ class VMStorageLocal {
       return try FileManager.default.contentsOfDirectory(
         at: baseURL,
         includingPropertiesForKeys: [.isDirectoryKey],
-        options: .skipsSubdirectoryDescendants).map { url in
+        options: .skipsSubdirectoryDescendants).compactMap { url in
         let vmDir = VMDirectory(baseURL: url)
 
+        if !vmDir.initialized {
+          return nil
+        }
+
         return (vmDir.name, vmDir)
       }
     } catch {

Sources/tart/VMStorageOCI.swift

@@ -1,12 +1,16 @@
 import Foundation
 
-class VMStorageOCI {
-  let baseURL = Config.tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
+class VMStorageOCI: PrunableStorage {
+  let baseURL = try! Config().tartCacheDir.appendingPathComponent("OCIs", isDirectory: true)
 
   private func vmURL(_ name: RemoteName) -> URL {
     baseURL.appendingRemoteName(name)
   }
 
+  private func hostDirectoryURL(_ name: RemoteName) -> URL {
+    baseURL.appendingHost(name)
+  }
+
   func exists(_ name: RemoteName) -> Bool {
     VMDirectory(baseURL: vmURL(name)).initialized
   }
@@ -16,6 +20,8 @@ class VMStorageOCI {
 
     try vmDir.validate()
 
+    try vmDir.baseURL.updateAccessDate()
+
     return vmDir
   }
 
@@ -27,12 +33,61 @@ class VMStorageOCI {
     return vmDir
   }
 
-  func delete(_ name: RemoteName) throws {
-    try FileManager.default.removeItem(at: vmURL(name))
+  func move(_ name: RemoteName, from: VMDirectory) throws{
+    let targetURL = vmURL(name)
+
+    // Pre-create intermediate directories (e.g. creates ~/.tart/cache/OCIs/github.com/org/repo/
+    // for github.com/org/repo:latest)
+    try FileManager.default.createDirectory(at: targetURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true)
+
+    _ = try FileManager.default.replaceItemAt(targetURL, withItemAt: from.baseURL)
   }
 
-  func list() throws -> [(String, VMDirectory)] {
-    var result: [(String, VMDirectory)] = Array()
+  func delete(_ name: RemoteName) throws {
+    try FileManager.default.removeItem(at: vmURL(name))
+    try gc()
+  }
+
+  func gc() throws {
+    var refCounts = Dictionary<URL, UInt>()
+
+    guard let enumerator = FileManager.default.enumerator(at: baseURL,
+            includingPropertiesForKeys: [.isSymbolicLinkKey]) else {
+      return
+    }
+
+    for case let foundURL as URL in enumerator {
+      let isSymlink = try foundURL.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink!
+
+      // Perform garbage collection for tag-based images
+      // with broken outgoing references
+      if isSymlink && foundURL == foundURL.resolvingSymlinksInPath() {
+        try FileManager.default.removeItem(at: foundURL)
+        continue
+      }
+
+      let vmDir = VMDirectory(baseURL: foundURL.resolvingSymlinksInPath())
+      if !vmDir.initialized {
+        continue
+      }
+
+      refCounts[vmDir.baseURL] = (refCounts[vmDir.baseURL] ?? 0) + (isSymlink ? 1 : 0)
+    }
+
+    // Perform garbage collection for digest-based images
+    // with no incoming references
+    for (baseURL, incRefCount) in refCounts {
+      let vmDir = VMDirectory(baseURL: baseURL)
+
+      if !vmDir.isExplicitlyPulled() && incRefCount == 0 {
+        try FileManager.default.removeItem(at: baseURL)
+      }
+    }
+  }
+
+  func list() throws -> [(String, VMDirectory, Bool)] {
+    var result: [(String, VMDirectory, Bool)] = Array()
 
     guard let enumerator = FileManager.default.enumerator(at: baseURL,
       includingPropertiesForKeys: [.isSymbolicLinkKey], options: [.producesRelativePathURLs]) else {
@@ -49,42 +104,98 @@ class VMStorageOCI {
       let parts = [foundURL.deletingLastPathComponent().relativePath, foundURL.lastPathComponent]
       var name: String
 
-      if try foundURL.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink! {
+      let isSymlink = try foundURL.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink!
+      if isSymlink {
         name = parts.joined(separator: ":")
       } else {
         name = parts.joined(separator: "@")
       }
 
-      result.append((name, vmDir))
+      result.append((name, vmDir, isSymlink))
     }
 
     return result
   }
 
+  func prunables() throws -> [Prunable] {
+    try list().filter { (_, _, isSymlink) in !isSymlink }.map { (_, vmDir, _) in vmDir }
+  }
+
   func pull(_ name: RemoteName, registry: Registry) async throws {
     defaultLogger.appendNewLine("pulling manifest...")
 
-    let (manifest, manifestData) = try await registry.pullManifest(reference: name.reference)
+    let (manifest, manifestData) = try await registry.pullManifest(reference: name.reference.value)
 
-    // Create directory for manifest's digest
-    var digestName = name
-    digestName.reference = Digest.hash(manifestData)
-    if !exists(digestName) {
-      let vmDir = try create(digestName)
-      try await vmDir.pullFromRegistry(registry: registry, manifest: manifest)
-    } else {
-      defaultLogger.appendNewLine("\(digestName.reference) image is already cached! creating a symlink...")   
+    let digestName = RemoteName(host: name.host, namespace: name.namespace,
+            reference: Reference(digest: Digest.hash(manifestData)))
+
+    // Ensure that host directory for given RemoteName exists in OCI storage
+    let hostDirectoryURL = hostDirectoryURL(digestName)
+    try FileManager.default.createDirectory(at: hostDirectoryURL, withIntermediateDirectories: true)
+
+    // Acquire a lock on it to prevent concurrent pulls for a single host
+    let lock = try FileLock(lockURL: hostDirectoryURL)
+
+    let sucessfullyLocked = try lock.trylock()
+    if !sucessfullyLocked {
+      print("waiting for lock...")
+      try lock.lock()
+    }
+    defer { try! lock.unlock() }
+
+    if Task.isCancelled {
+      throw CancellationError()
     }
 
-    // Create directory for reference if it's different
-    if digestName != name {
-      // Overwrite the old symbolic link
-      if FileManager.default.fileExists(atPath: vmURL(name).path) {
-        try FileManager.default.removeItem(at: vmURL(name))
+    if !exists(digestName) {
+      let tmpVMDir = try VMDirectory.temporary()
+
+      // Lock the temporary VM directory to prevent it's garbage collection
+      let tmpVMDirLock = try FileLock(lockURL: tmpVMDir.baseURL)
+      try tmpVMDirLock.lock()
+
+      // Try to reclaim some cache space if we know the VM size in advance
+      if let uncompressedDiskSize = manifest.uncompressedDiskSize() {
+        let requiredCapacityBytes = UInt64(uncompressedDiskSize + 128 * 1024 * 1024)
+
+        let attrs = try Config().tartCacheDir.resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey, .volumeAvailableCapacityKey])
+        let availableCapacityBytes = max(UInt64(attrs.volumeAvailableCapacityForImportantUsage!), UInt64(attrs.volumeAvailableCapacity!))
+
+        // There is a suspicious that occasionally capacity is returned as zero which can't be true.
+        // Let's validate to avoid unnecessary pruning.
+        if 0 < availableCapacityBytes && availableCapacityBytes < requiredCapacityBytes {
+          try Prune.pruneReclaim(reclaimBytes: requiredCapacityBytes - availableCapacityBytes)
+        }
       }
 
-      try FileManager.default.createSymbolicLink(at: vmURL(name), withDestinationURL: vmURL(digestName))
+      try await withTaskCancellationHandler(operation: {
+        try await tmpVMDir.pullFromRegistry(registry: registry, manifest: manifest)
+        try move(digestName, from: tmpVMDir)
+      }, onCancel: {
+        try? FileManager.default.removeItem(at: tmpVMDir.baseURL)
+      })
+    } else {
+      defaultLogger.appendNewLine("\(digestName) image is already cached! creating a symlink...")
     }
+
+    if name != digestName {
+      // Create new or overwrite the old symbolic link
+      try link(from: digestName, to: name)
+    } else {
+      // Ensure that images pulled by content digest
+      // are excluded from garbage collection
+      VMDirectory(baseURL: vmURL(name)).markExplicitlyPulled()
+    }
+  }
+
+  func link(from: RemoteName, to: RemoteName) throws {
+    if FileManager.default.fileExists(atPath: vmURL(to).path) {
+      try FileManager.default.removeItem(at: vmURL(to))
+    }
+
+    try FileManager.default.createSymbolicLink(at: vmURL(to), withDestinationURL: vmURL(from))
+
+    try gc()
   }
 }
 
@@ -92,10 +203,14 @@ extension URL {
   func appendingRemoteName(_ name: RemoteName) -> URL {
     var result: URL = self
 
-    for pathComponent in (name.host + "/" + name.namespace + "/" + name.reference).split(separator: "/") {
+    for pathComponent in (name.host + "/" + name.namespace + "/" + name.reference.value).split(separator: "/") {
       result = result.appendingPathComponent(String(pathComponent))
     }
 
     return result
   }
+
+  func appendingHost(_ name: RemoteName) -> URL {
+    self.appendingPathComponent(name.host, isDirectory: true)
+  }
 }

Sources/tart/VNC/FullFledgedVNC.swift

@@ -0,0 +1,38 @@
+import Foundation
+import Dynamic
+import Virtualization
+
+class FullFledgedVNC: VNC {
+    let password: String
+    private let vnc: Dynamic
+
+    init(virtualMachine: VZVirtualMachine) {
+        password = Array(PassphraseGenerator().prefix(4)).joined(separator: "-")
+        let securityConfiguration = Dynamic._VZVNCAuthenticationSecurityConfiguration(password: password)
+        vnc = Dynamic._VZVNCServer(port: 0, queue: DispatchQueue.global(),
+                securityConfiguration: securityConfiguration)
+        vnc.virtualMachine = virtualMachine
+        vnc.start()
+    }
+
+    func waitForURL() async throws -> URL {
+      while true {
+        // Port is 0 shortly after start(),
+        // but will be initialized later
+        if let port = vnc.port.asUInt16, port != 0 {
+          return URL(string: "vnc://:\(password)@127.0.0.1:\(port)")!
+        }
+
+        // Wait 50 ms.
+        try await Task.sleep(nanoseconds: 50_000_000)
+      }
+    }
+
+    func stop() throws {
+        vnc.stop()
+    }
+
+    deinit {
+        try? stop()
+    }
+}

Sources/tart/VNC/ScreenSharingVNC.swift

@@ -0,0 +1,26 @@
+import Foundation
+import Dynamic
+import Virtualization
+
+class ScreenSharingVNC: VNC {
+  let vmConfig: VMConfig
+
+  init(vmConfig: VMConfig) {
+    self.vmConfig = vmConfig
+  }
+
+  func waitForURL() async throws -> URL {
+    let vmMACAddress = MACAddress(fromString: vmConfig.macAddress.string)!
+    let ip = try await IP.resolveIP(vmMACAddress, secondsToWait: 60)
+
+    if let ip = ip {
+      return URL(string: "vnc://\(ip)")!
+    }
+
+    throw IPNotFound()
+  }
+
+  func stop() throws {
+    // nothing to do
+  }
+}

Sources/tart/VNC/VNC.swift

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

Tests/TartTests/FileLockTests.swift

@@ -0,0 +1,34 @@
+import XCTest
+@testable import tart
+
+final class FileLockTests: XCTestCase {
+    func testSimple() throws {
+        // Create a temporary file that will be used as a lock
+        let url = temporaryFile()
+
+        // Make sure this file can be locked and unlocked
+        let lock = try FileLock(lockURL: url)
+        try lock.lock()
+        try lock.unlock()
+    }
+
+    func testDoubleLockResultsInError() throws {
+        // Create a temporary file that will be used as a lock
+        let url = temporaryFile()
+
+        // Create two locks on a same file and ensure one of them fails
+        let firstLock = try FileLock(lockURL: url)
+        try firstLock.lock()
+
+        let secondLock = try! FileLock(lockURL: url)
+        XCTAssertFalse(try secondLock.trylock())
+    }
+
+    private func temporaryFile() -> URL {
+        let url = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString)
+
+        FileManager.default.createFile(atPath: url.path, contents: nil)
+
+        return url
+    }
+}

Tests/TartTests/MACAddressResolverTests.swift

@@ -0,0 +1,35 @@
+import XCTest
+import Network
+@testable import tart
+
+final class MACAddressResolverTests: XCTestCase {
+  func testSingleEntry() throws {
+    let leases = try Leases("""
+                            {
+                              ip_address=1.2.3.4
+                              hw_address=1,00:11:22:33:44:55
+                            }
+                            """)
+
+    XCTAssertEqual(IPv4Address("1.2.3.4"),
+      try leases.resolveMACAddress(macAddress: MACAddress(fromString: "00:11:22:33:44:55")!))
+  }
+
+  func testMultipleEntries() throws {
+    let leases = try Leases("""
+                            {
+                              ip_address=1.2.3.4
+                              hw_address=1,00:11:22:33:44:55
+                            }
+                            {
+                              ip_address=5.6.7.8
+                              hw_address=1,AA:BB:CC:DD:EE:FF
+                            }
+                            """)
+
+    XCTAssertEqual(IPv4Address("1.2.3.4"),
+      try 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")!))
+  }
+}

Tests/TartTests/RegistryTests.swift

@@ -0,0 +1,89 @@
+import XCTest
+@testable import tart
+
+final class RegistryTests: XCTestCase {
+    var registryRunner: RegistryRunner?
+
+    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
+    }
+
+    var registry: Registry {
+        registryRunner!.registry
+    }
+
+    func testPushPullBlobSmall() async throws {
+        // Generate a simple blob
+        let pushedBlob = Data("The quick brown fox jumps over the lazy dog".utf8)
+
+        // Push it
+        let pushedBlobDigest = try await registry.pushBlob(fromData: pushedBlob)
+        XCTAssertEqual("sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592", pushedBlobDigest)
+
+        // Pull it
+        var pulledBlob = Data()
+        try await registry.pullBlob(pushedBlobDigest) { buffer in
+            pulledBlob.append(Data(buffer: buffer))
+        }
+
+        // Ensure that both blobs are identical
+        XCTAssertEqual(pushedBlob, pulledBlob)
+    }
+
+    func testPushPullBlobHugeInChunks() async throws {
+        // Generate a large enough blob
+        let fh = FileHandle(forReadingAtPath: "/dev/urandom")!
+        let largeBlobToPush = try fh.read(upToCount: 768 * 1024 * 1024)!
+
+        // Push it
+        let largeBlobDigest = try await registry.pushBlob(fromData: largeBlobToPush, chunkSizeMb: 10)
+
+        // Pull it
+        var pulledLargeBlob = Data()
+        try await registry.pullBlob(largeBlobDigest) { buffer in
+            pulledLargeBlob.append(Data(buffer: buffer))       
+        }
+
+        // Ensure that both blobs are identical
+        XCTAssertEqual(largeBlobToPush, pulledLargeBlob)
+    }
+
+    func testPushPullManifest() async throws {
+        // Craft a basic config
+        let configData = try OCIConfig().toJSON()
+        let configDigest = try await registry.pushBlob(fromData: configData)
+
+        // Craft a basic layer
+        let layerData = Data("doesn't matter".utf8)
+        let layerDigest = try await registry.pushBlob(fromData: layerData)
+
+        // Craft a basic manifest and push it
+        let manifest = OCIManifest(
+                config: OCIManifestConfig(size: configData.count, digest: configDigest),
+                layers: [
+                    OCIManifestLayer(mediaType: "application/octet-stream", size: layerData.count, digest: layerDigest)
+                ]
+        )
+        let pushedManifestDigest = try await registry.pushManifest(reference: "latest", manifest: manifest)
+
+        // Ensure that the manifest pulled by tag matches with the one pushed above
+        let (pulledByTagManifest, _) = try await registry.pullManifest(reference: "latest")
+        XCTAssertEqual(manifest, pulledByTagManifest)
+
+        // Ensure that the manifest pulled by digest matches with the one pushed above
+        let (pulledByDigestManifest, _) = try await registry.pullManifest(reference: "\(pushedManifestDigest)")
+        XCTAssertEqual(manifest, pulledByDigestManifest)
+    }
+}

Tests/TartTests/RemoteNameTests.swift

@@ -3,16 +3,22 @@ import XCTest
 
 final class RemoteNameTests: XCTestCase {
   func testTag() throws {
-    let expectedRemoteName = RemoteName(host: "ghcr.io", namespace: "a/b", reference: "latest")
+    let expectedRemoteName = RemoteName(host: "ghcr.io", namespace: "a/b", reference: Reference(tag: "latest"))
 
     XCTAssertEqual(expectedRemoteName, try RemoteName("ghcr.io/a/b:latest"))
   }
+  
+  func testComplexTag() throws {
+    let expectedRemoteName = RemoteName(host: "ghcr.io", namespace: "a/b", reference: Reference(tag: "1.2.3-RC-1"))
+
+    XCTAssertEqual(expectedRemoteName, try RemoteName("ghcr.io/a/b:1.2.3-RC-1"))
+  }
 
   func testDigest() throws {
     let expectedRemoteName = RemoteName(
       host: "ghcr.io",
       namespace: "a/b",
-      reference: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      reference: Reference(digest: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
     )
 
     XCTAssertEqual(expectedRemoteName,

Tests/TartTests/TokenResponseTests.swift

@@ -11,7 +11,7 @@ final class TokenResponseTests: XCTestCase {
     let expectedTokenExpiresAtRange = Date()...Date().addingTimeInterval(60)
     XCTAssertTrue(expectedTokenExpiresAtRange.contains(tokenResponse.tokenExpiresAt))
 
-    XCTAssertTrue(tokenResponse.isValid)
+    XCTAssertTrue(tokenResponse.isValid())
   }
 
   func testExpirationBasic() throws {
@@ -23,9 +23,9 @@ final class TokenResponseTests: XCTestCase {
     let expectedTokenExpiresAtRange = Date()...Date().addingTimeInterval(2)
     XCTAssertTrue(expectedTokenExpiresAtRange.contains(tokenResponse.tokenExpiresAt))
 
-    XCTAssertTrue(tokenResponse.isValid)
+    XCTAssertTrue(tokenResponse.isValid())
     _ = XCTWaiter.wait(for: [expectation(description: "Wait 3 seconds for the token to become invalid")], timeout: 2)
-    XCTAssertFalse(tokenResponse.isValid)
+    XCTAssertFalse(tokenResponse.isValid())
   }
 
   func testExpirationWithIssuedAt() throws {
@@ -33,6 +33,6 @@ final class TokenResponseTests: XCTestCase {
     let tokenResponse = try TokenResponse.parse(fromData: tokenResponseRaw)
 
     XCTAssertEqual(Date(timeIntervalSince1970: 3600), tokenResponse.tokenExpiresAt)
-    XCTAssertFalse(tokenResponse.isValid)
+    XCTAssertFalse(tokenResponse.isValid())
   }
 }

Tests/TartTests/URLAccessDateTests.swift

@@ -0,0 +1,22 @@
+import XCTest
+@testable import tart
+
+final class URLAccessDateTests: XCTestCase {
+  func testGetAndSetAccessTime() throws {
+    // Create a temporary file
+    let tmpDir = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+    var tmpFile = tmpDir.appendingPathComponent(UUID().uuidString)
+    FileManager.default.createFile(atPath: tmpFile.path, contents: nil)
+
+    // Ensure it's access date is different than our desired access date
+    let arbitraryDate = Date.init(year: 2008, month: 09, day: 28, hour: 23, minute: 15)
+    XCTAssertNotEqual(arbitraryDate, try tmpFile.accessDate())
+
+    // Set our desired access date for a file
+    try tmpFile.updateAccessDate(arbitraryDate)
+
+    // Ensure the access date has changed to our value
+    tmpFile.removeCachedResourceValue(forKey: .contentAccessDateKey)
+    XCTAssertEqual(arbitraryDate, try tmpFile.accessDate())
+  }
+}

Tests/TartTests/Util/RegistryRunner.swift

@@ -0,0 +1,54 @@
+import Foundation
+@testable import tart
+
+enum RegistryRunnerError: Error {
+    case DockerFailed(exitCode: Int32)
+}
+
+class RegistryRunner {
+    let containerID: String
+    let registry: Registry
+
+    static func dockerCmd(_ arguments: String...) throws -> String {
+        let stdoutPipe = Pipe()
+
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: "/usr/local/bin/docker")
+        proc.arguments = arguments
+        proc.standardOutput = stdoutPipe
+        try proc.run()
+
+        let stdoutData = stdoutPipe.fileHandleForReading.readDataToEndOfFile()
+
+        proc.waitUntilExit()
+
+        if proc.terminationStatus != 0 {
+            throw RegistryRunnerError.DockerFailed(exitCode: proc.terminationStatus)
+        }
+
+        return String(data: stdoutData, encoding: .utf8) ?? ""
+    }
+
+    init() async throws {
+        // Start container
+        let container = try Self.dockerCmd("run", "-d", "--rm", "-p", "5000", "registry:2")
+                .trimmingCharacters(in: CharacterSet.newlines)
+        containerID = container
+
+        // Get forwarded port
+        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/")!,
+                namespace: "vm-image")
+
+        // Wait for the Docker Registry to start
+        while ((try? await registry.ping()) == nil) {
+            try await Task.sleep(nanoseconds: 100_000_000)
+        }
+    }
+
+    deinit {
+        _ = try! Self.dockerCmd("kill", containerID)
+    }
+}

gon.hcl

@@ -0,0 +1,12 @@
+source = [".build/arm64-apple-macosx/debug/tart"]
+bundle_id = "com.github.cirruslabs.tart"
+
+apple_id {
+  username = "hello@cirruslabs.org"
+  password = "@env:AC_PASSWORD"
+}
+
+sign {
+  application_identity = "Developer ID Application: Fedor Korotkov"
+  entitlements_file = "Resources/tart.entitlements"
+}