feat: Add disk image format selection with ASIF support (#1094 )

* feat: Add disk image format selection with ASIF support * fixed goreleaser-pro * Fix ASIF disk format compatibility issues - Use .uncached caching mode for ASIF disks to avoid Virtualization framework compatibility issues - Improve caching mode selection logic for better maintainability - Fix compiler warning by changing var to let for attachment variable This resolves VM startup failures when using ASIF disk format by ensuring proper disk attachment configuration. * Update goreleaser installation to use tap-specific formula Change from 'brew install --cask goreleaser-pro' to 'brew install --cask goreleaser/tap/goreleaser-pro' for proper installation from the official goreleaser tap. * Remove VS Code configuration and add to gitignore - Remove .vscode/launch.json from repository - Add .vscode/ to .gitignore to prevent VS Code settings from being tracked * Implement ASIF disk resize using diskutil - Add support for resizing ASIF disk images using diskutil image resize - Detect disk format from VM config and route to appropriate resize method - Use diskutil image info to get current ASIF disk size and validate resize - Remove restriction that prevented ASIF disk resizing in Set command - Add FailedToResizeDisk error case for proper error handling - Maintain backward compatibility with raw disk resizing - Add comprehensive size validation to prevent data loss * Update Sources/tart/Commands/Create.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Update Sources/tart/DiskImageFormat.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Update Sources/tart/DiskImageFormat.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Fix test naming and remove redundant test cases - Rename testFormatArgument to testCaseInsensitivity for clarity - Remove redundant 'raw' and 'invalid' test cases already covered in testFormatFromString - Remove testFormatDescriptions test as it's not very useful Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152093510 * Remove canCreate property and simplify DiskImageFormat - Remove canCreate property since it's the same as isSupported - Remove description property entirely as it's not used - Fix displayName for RAW format (remove UDIF reference) - Remove checkDiskutilASIFSupport helper function Addresses review comments: - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152109450 - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152115610 - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152124330 * Update Create command validation and help text - Simplify ArgumentParser help text to let it show possible values automatically - Remove canCreate validation since property was removed - Simplify error message for unsupported disk formats Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152113480 * Add disk format validation to Run command - Add validation to ensure ASIF disk format is supported on current system - Check disk format compatibility before attempting to run VM Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152109450 * Use proper namespaced constant for OCI label - Add diskFormatLabelAnnotation constant in Manifest.swift - Use org.cirruslabs.tart.disk.format namespace for consistency - Use variable shadowing instead of new variable name for labels Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152163515 * Remove special ASIF caching mode - Remove .uncached caching mode for ASIF disks - Use default caching logic for all disk formats - Testing shows .cached mode works fine on macOS 26.0 Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152133589 * Improve code structure in VMDirectory - Use guard let instead of nested if let for better readability - Reduce nesting in resizeASIFDisk function - Improve error handling flow Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152141916 * diskFormatLabel * reverted caching mode * Use PropertyListDecoder --------- Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com>
tart ip: implement --resolver=agent (#1095 )
2026-10-02 04:01:12 +02:00 · 2025-06-19 18:27:30 +04:00 · 2025-06-19 13:07:06 +04:00 · 2025-06-11 20:15:18 +02:00 · 2025-06-11 21:58:30 +04:00 · 2025-06-01 19:54:45 -04:00
24 changed files with 1026 additions and 75 deletions
@@ -83,8 +83,9 @@ task:
    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
  install_script:
-    - brew install go goreleaser/tap/goreleaser-pro
+    - brew install go
    - brew install mitchellh/gon/gon
+    - brew install --cask goreleaser/tap/goreleaser-pro
  info_script:
    - security find-identity -v
    - xcodebuild -version
@@ -121,8 +122,9 @@ task:
    - security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k password101 build.keychain
    - xcrun notarytool store-credentials "notarytool" --apple-id "hello@cirruslabs.org" --team-id "9M2P8L4D89" --password $AC_PASSWORD
  install_script:
-    - brew install go goreleaser/tap/goreleaser-pro getsentry/tools/sentry-cli
+    - brew install go getsentry/tools/sentry-cli
    - brew install mitchellh/gon/gon
+    - brew install --cask goreleaser/tap/goreleaser-pro
  info_script:
    - security find-identity -v
    - xcodebuild -version
@@ -8,6 +8,9 @@ tart.xcodeproj/
 # AppCode
 .idea/

+# VS Code
+.vscode/
+
 # Swift
 .build/

@@ -1,5 +1,5 @@
 {
-  "originHash" : "22b3726bc4e4c6e9c04ac97cb08a82967feb39960a93d2909768a16e11576748",
+  "originHash" : "c5371137580239f6928cf64425e754e77680bf24430b50f02dad5558c23f68b0",
  "pins" : [
    {
      "identity" : "antlr4",
@@ -10,6 +10,24 @@
        "version" : "4.13.2"
      }
    },
+    {
+      "identity" : "cirruslabs_tart-guest-agent_apple_swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://buf.build/gen/swift/git/1.28.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_apple_swift.git",
+      "state" : {
+        "revision" : "ccfae5de1917cdb0d7c5000008fa5ed0bad032bf",
+        "version" : "1.28.2-00000000000000-17d7dedafb88.1"
+      }
+    },
+    {
+      "identity" : "cirruslabs_tart-guest-agent_grpc_swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://buf.build/gen/swift/git/1.24.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_grpc_swift.git",
+      "state" : {
+        "branch" : "1.24.2-00000000000000-17d7dedafb88.1",
+        "revision" : "b8421f137325fe8de737ff5b61238f6f2131b2a8"
+      }
+    },
    {
      "identity" : "dynamic",
      "kind" : "remoteSourceControl",
@@ -19,6 +37,15 @@
        "revision" : "772883073d044bc754d401cabb6574624eb3778f"
      }
    },
+    {
+      "identity" : "grpc-swift",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/grpc/grpc-swift.git",
+      "state" : {
+        "revision" : "8c5e99d0255c373e0330730d191a3423c57373fb",
+        "version" : "1.24.2"
+      }
+    },
    {
      "identity" : "semaphore",
      "kind" : "remoteSourceControl",
@@ -33,8 +60,8 @@
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/getsentry/sentry-cocoa",
      "state" : {
-        "revision" : "5575af93efb776414f243e93d6af9f6258dc539a",
-        "version" : "8.36.0"
+        "revision" : "65b3d2a7608685e8d4a37c68fa2c64f28d0b537e",
+        "version" : "8.51.1"
      }
    },
    {
@@ -64,6 +91,33 @@
        "version" : "1.2.0"
      }
    },
+    {
+      "identity" : "swift-collections",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-collections.git",
+      "state" : {
+        "revision" : "671108c96644956dddcd89dd59c203dcdb36cec7",
+        "version" : "1.1.4"
+      }
+    },
+    {
+      "identity" : "swift-http-structured-headers",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-structured-headers.git",
+      "state" : {
+        "revision" : "db6eea3692638a65e2124990155cd220c2915903",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-http-types",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-http-types.git",
+      "state" : {
+        "revision" : "a0a57e949a8903563aba4615869310c0ebf14c03",
+        "version" : "1.4.0"
+      }
+    },
    {
      "identity" : "swift-log",
      "kind" : "remoteSourceControl",
@@ -73,6 +127,51 @@
        "version" : "1.6.1"
      }
    },
+    {
+      "identity" : "swift-nio",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio.git",
+      "state" : {
+        "revision" : "34d486b01cd891297ac615e40d5999536a1e138d",
+        "version" : "2.83.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-extras",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-extras.git",
+      "state" : {
+        "revision" : "f1f6f772198bee35d99dd145f1513d8581a54f2c",
+        "version" : "1.26.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-http2",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-http2.git",
+      "state" : {
+        "revision" : "4281466512f63d1bd530e33f4aa6993ee7864be0",
+        "version" : "1.36.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-ssl",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-ssl.git",
+      "state" : {
+        "revision" : "4b38f35946d00d8f6176fe58f96d83aba64b36c7",
+        "version" : "2.31.0"
+      }
+    },
+    {
+      "identity" : "swift-nio-transport-services",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-nio-transport-services.git",
+      "state" : {
+        "revision" : "cd1e89816d345d2523b11c55654570acd5cd4c56",
+        "version" : "1.24.0"
+      }
+    },
    {
      "identity" : "swift-numerics",
      "kind" : "remoteSourceControl",
@@ -82,6 +181,15 @@
        "version" : "1.0.2"
      }
    },
+    {
+      "identity" : "swift-protobuf",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-protobuf.git",
+      "state" : {
+        "revision" : "ebc7251dd5b37f627c93698e4374084d98409633",
+        "version" : "1.28.2"
+      }
+    },
    {
      "identity" : "swift-retry",
      "kind" : "remoteSourceControl",
@@ -100,6 +208,15 @@
        "version" : "1.8.0"
      }
    },
+    {
+      "identity" : "swift-system",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-system.git",
+      "state" : {
+        "revision" : "a34201439c74b53f0fd71ef11741af7e7caf01e1",
+        "version" : "1.4.2"
+      }
+    },
    {
      "identity" : "swift-xattr",
      "kind" : "remoteSourceControl",
@@ -17,13 +17,15 @@ let package = Package(
    .package(url: "https://github.com/antlr/antlr4", exact: "4.13.2"),
    .package(url: "https://github.com/apple/swift-atomics.git", .upToNextMajor(from: "1.2.0")),
    .package(url: "https://github.com/nicklockwood/SwiftFormat", from: "0.53.6"),
-    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.36.0"),
+    .package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.51.1"),
    .package(url: "https://github.com/cfilipov/TextTable", branch: "master"),
    .package(url: "https://github.com/sersoft-gmbh/swift-sysctl.git", from: "1.8.0"),
    .package(url: "https://github.com/orchetect/SwiftRadix", from: "1.3.1"),
    .package(url: "https://github.com/groue/Semaphore", from: "0.0.8"),
    .package(url: "https://github.com/fumoboy007/swift-retry", from: "0.2.3"),
    .package(url: "https://github.com/jozefizso/swift-xattr", from: "3.0.0"),
+    .package(url: "https://github.com/grpc/grpc-swift.git", .upToNextMajor(from: "1.24.2")),
+    .package(url: "https://buf.build/gen/swift/git/1.24.2-00000000000000-17d7dedafb88.1/cirruslabs_tart-guest-agent_grpc_swift.git", revision: "1.24.2-00000000000000-17d7dedafb88.1"),
  ],
  targets: [
    .executableTarget(name: "tart", dependencies: [
@@ -40,6 +42,8 @@ let package = Package(
      .product(name: "Semaphore", package: "Semaphore"),
      .product(name: "DMRetry", package: "swift-retry"),
      .product(name: "XAttr", package: "swift-xattr"),
+      .product(name: "GRPC", package: "grpc-swift"),
+      .product(name: "Cirruslabs_TartGuestAgent_Grpc_Swift", package: "cirruslabs_tart-guest-agent_grpc_swift"),
    ], exclude: [
      "OCI/Reference/Makefile",
      "OCI/Reference/Reference.g4",
@@ -19,6 +19,9 @@ struct Create: AsyncParsableCommand {
  @Option(help: ArgumentHelp("Disk size in GB"))
  var diskSize: UInt16 = 50

+  @Option(help: ArgumentHelp("Disk image format", discussion: "ASIF format provides better performance but requires macOS 26 Tahoe or later"))
+  var diskFormat: DiskImageFormat = .raw
+
  func validate() throws {
    if fromIPSW == nil && !linux {
      throw ValidationError("Please specify either a --from-ipsw or --linux option!")
@@ -28,6 +31,11 @@ struct Create: AsyncParsableCommand {
        throw ValidationError("Only Linux VMs are supported on Intel!")
      }
    #endif
+
+    // Validate disk format support
+    if !diskFormat.isSupported {
+      throw ValidationError("Disk format '\(diskFormat.rawValue)' is not supported on this system.")
+    }
  }

  func run() async throws {
@@ -58,12 +66,12 @@ struct Create: AsyncParsableCommand {
            ipswURL = URL(fileURLWithPath: NSString(string: fromIPSW).expandingTildeInPath)
          }

-          _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize)
+          _ = try await VM(vmDir: tmpVMDir, ipswURL: ipswURL, diskSizeGB: diskSize, diskFormat: diskFormat)
        }
      #endif

      if linux {
-        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize)
+        _ = try await VM.linux(vmDir: tmpVMDir, diskSizeGB: diskSize, diskFormat: diskFormat)
      }

      try VMStorageLocal().move(name, from: tmpVMDir)
@@ -0,0 +1,180 @@
+import ArgumentParser
+import Foundation
+import NIOPosix
+import GRPC
+import Cirruslabs_TartGuestAgent_Grpc_Swift
+
+struct ExecCustomExitCodeError: Error {
+  let exitCode: Int32
+}
+
+struct Exec: AsyncParsableCommand {
+  static var configuration = CommandConfiguration(abstract: "Execute a command in a running VM", discussion: """
+  Requires Tart Guest Agent running in a guest VM.
+
+  Note that all non-vanilla Cirrus Labs VM images already have the Tart Guest Agent installed.
+  """)
+
+  @Flag(name: [.customShort("i")], help: "Attach host's standard input to a remote command")
+  var interactive: Bool = false
+
+  @Flag(name: [.customShort("t")], help: "Allocate a remote pseudo-terminal (PTY)")
+  var tty: Bool = false
+
+  @Argument(help: "VM name", completion: .custom(completeLocalMachines))
+  var name: String
+
+  @Argument(parsing: .captureForPassthrough, help: "Command to execute")
+  var command: [String]
+
+  func run() async throws {
+    // We only have withThrowingDiscardingTaskGroup available starting from macOS 14
+    if #unavailable(macOS 14) {
+      throw RuntimeError.Generic("\"tart exec\" is only available on macOS 14 (Sonoma) or newer")
+    }
+
+    // Open VM's directory
+    let vmDir = try VMStorageLocal().open(name)
+
+    // Ensure that the VM is running
+    if try !vmDir.running() {
+      throw RuntimeError.VMNotRunning(name)
+    }
+
+    // Create a gRPC channel connected to the VM's control socket
+    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    defer {
+      try! group.syncShutdownGracefully()
+    }
+
+    let channel = try GRPCChannelPool.with(
+      target: .unixDomainSocket(vmDir.controlSocketURL.path()),
+      transportSecurity: .plaintext,
+      eventLoopGroup: group,
+    )
+    defer {
+      try! channel.close().wait()
+    }
+
+    // Switch controlling terminal into raw mode when remote pseudo-terminal is requested
+    var state: State? = nil
+
+    if tty && Term.IsTerminal() {
+      state = try Term.MakeRaw()
+    }
+    defer {
+      // Restore terminal to its initial state
+      if let state {
+        try! Term.Restore(state)
+      }
+    }
+
+    // Execute a command in a running VM
+    do {
+      try await execute(channel)
+    } catch let error as GRPCConnectionPoolError {
+      throw RuntimeError.Generic("Failed to connect to the VM using its control socket: \(error.localizedDescription), is the Tart Guest Agent running?")
+    }
+  }
+
+  private func execute(_ channel: GRPCChannel) async throws {
+    let agentAsyncClient = AgentAsyncClient(channel: channel)
+    let execCall = agentAsyncClient.makeExecCall()
+
+    try await execCall.requestStream.send(.with {
+      $0.type = .command(.with {
+        $0.name = command[0]
+        $0.args = Array(command.dropFirst(1))
+        $0.interactive = interactive
+        $0.tty = tty
+        $0.terminalSize = .with {
+          let (width, height) = try! Term.GetSize()
+
+          $0.cols = UInt32(width)
+          $0.rows = UInt32(height)
+        }
+      })
+    })
+
+    // Process command events and optionally send our standard input and/or terminal dimensions
+    try await withThrowingTaskGroup { group in
+      // Stream host's standard input if interactive mode is enabled
+      if interactive {
+        let stdinStream = AsyncStream<Data> { continuation in
+          let handle = FileHandle.standardInput
+
+          handle.readabilityHandler = { handle in
+            let data = handle.availableData
+
+            continuation.yield(data)
+
+            if data.isEmpty {
+              continuation.finish()
+            }
+          }
+        }
+
+        group.addTask {
+          for await stdinData in stdinStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .standardInput(.with {
+                $0.data = stdinData
+              })
+            })
+          }
+        }
+      }
+
+      // Stream host's terminal dimensions if pseudo-terminal is requested
+      signal(SIGWINCH, SIG_IGN)
+      let sigwinchSrc = DispatchSource.makeSignalSource(signal: SIGWINCH)
+      sigwinchSrc.activate()
+
+      if tty {
+        let terminalDimensionsStream = AsyncStream { continuation in
+          sigwinchSrc.setEventHandler {
+            continuation.yield(try! Term.GetSize())
+          }
+        }
+
+        group.addTask {
+          for await (width, height) in terminalDimensionsStream {
+            try await execCall.requestStream.send(.with {
+              $0.type = .terminalResize(.with {
+                $0.cols = UInt32(width)
+                $0.rows = UInt32(height)
+              })
+            })
+          }
+        }
+      }
+
+      // Process command events
+      group.addTask {
+        for try await response in execCall.responseStream {
+          switch response.type {
+          case .standardOutput(let ioChunk):
+            try FileHandle.standardOutput.write(contentsOf: ioChunk.data)
+          case .standardError(let ioChunk):
+            try FileHandle.standardError.write(contentsOf: ioChunk.data)
+          case .exit(let exit):
+            throw ExecCustomExitCodeError(exitCode: exit.code)
+          default:
+            // Unknown event, do nothing
+            continue
+          }
+        }
+      }
+
+      while !group.isEmpty {
+        do {
+          try await group.next()
+        } catch {
+          group.cancelAll()
+
+          throw error
+        }
+      }
+    }
+  }
+}
@@ -6,6 +6,7 @@ fileprivate struct VMInfo: Encodable {
  let CPU: Int
  let Memory: UInt64
  let Disk: Int
+  let DiskFormat: String
  let Size: String
  let Display: String
  let Running: Bool
@@ -26,7 +27,7 @@ struct Get: AsyncParsableCommand {
    let vmConfig = try VMConfig(fromURL: vmDir.configURL)
    let memorySizeInMb = vmConfig.memorySize / 1024 / 1024

-    let info = VMInfo(OS: vmConfig.os, CPU: vmConfig.cpuCount, Memory: memorySizeInMb, Disk: try vmDir.sizeGB(), Size: String(format: "%.3f", Float(try vmDir.allocatedSizeBytes()) / 1000 / 1000 / 1000), Display: vmConfig.display.description, Running: try vmDir.running(), State: try vmDir.state().rawValue)
+    let info = VMInfo(OS: vmConfig.os, CPU: vmConfig.cpuCount, Memory: memorySizeInMb, Disk: try vmDir.sizeGB(), DiskFormat: vmConfig.diskFormat.rawValue, Size: String(format: "%.3f", Float(try vmDir.allocatedSizeBytes()) / 1000 / 1000 / 1000), Display: vmConfig.display.description, Running: try vmDir.running(), State: try vmDir.state().rawValue)
    print(format.renderSingle(info))
  }
 }
@@ -5,9 +5,9 @@ import SystemConfiguration
 import Sentry

 enum IPResolutionStrategy: String, ExpressibleByArgument, CaseIterable {
-  case dhcp, arp
+  case dhcp, arp, agent

-  private(set) static var allValueStrings: [String] = Format.allCases.map { "\($0)"}
+  private(set) static var allValueStrings: [String] = Self.allCases.map { "\($0)"}
 }

 struct IP: AsyncParsableCommand {
@@ -19,13 +19,11 @@ struct IP: AsyncParsableCommand {
  @Option(help: "Number of seconds to wait for a potential VM booting")
  var wait: UInt16 = 0

-  @Option(help: ArgumentHelp("Strategy for resolving IP address: dhcp or arp",
+  @Option(help: ArgumentHelp("Strategy for resolving IP address",
                             discussion: """
-                             By default, Tart is looking up and parsing DHCP lease file to determine the IP of the VM.\n
-                             This method is fast and the most reliable but only returns local IP adresses.\n
-                             Alternatively, Tart can call external `arp` executable and parse it's output.\n
-                             In case of enabled Bridged Networking this method will return VM's IP address on the network interface used for Bridged Networking.\n
-                             Note that `arp` strategy won't work for VMs using `--net-softnet`.
+                             By default, Tart is using a "dhcp" resolver which parses the DHCP lease file on host and tries to find an entry containing the VM's MAC address. This method is fast and the most reliable, but only works for VMs are not using the bridged networking.\n
+                             Alternatively, Tart has an "arp" resolver which calls an external "arp" executable and parses it's output. This works for VMs using bridged networking and returns their IP, but when they generate enough network activity to populate the host's ARP table. Note that "arp" strategy won't work for VMs using the Softnet networking.\n
+                             A third strategy, "agent" works in all cases reliably, but requires Guest agent for Tart VMs (https://github.com/cirruslabs/tart-guest-agent) to be installed inside of a VM.
                             """))
  var resolver: IPResolutionStrategy = .dhcp

@@ -34,14 +32,16 @@ struct IP: AsyncParsableCommand {
    let vmConfig = try VMConfig.init(fromURL: vmDir.configURL)
    let vmMACAddress = MACAddress(fromString: vmConfig.macAddress.string)!

-    guard let ip = try await IP.resolveIP(vmMACAddress, resolutionStrategy: resolver, secondsToWait: wait) else {
+    guard let ip = try await IP.resolveIP(vmMACAddress, resolutionStrategy: resolver, secondsToWait: wait, controlSocketURL: vmDir.controlSocketURL) else {
      var message = "no IP address found"

      if try !vmDir.running() {
        message += ", is your VM running?"
      }

-      if (vmConfig.os == .linux && resolver == .arp) {
+      if (resolver == .agent) {
+        message += " (also make sure that Guest agent for Tart is running inside of a VM)"
+      } else if (vmConfig.os == .linux && resolver == .arp) {
        message += " (not all Linux distributions are compatible with the ARP resolver)"
      }

@@ -51,7 +51,7 @@ struct IP: AsyncParsableCommand {
    print(ip)
  }

-  static public func resolveIP(_ vmMACAddress: MACAddress, resolutionStrategy: IPResolutionStrategy = .dhcp, secondsToWait: UInt16 = 0) async throws -> IPv4Address? {
+  static public func resolveIP(_ vmMACAddress: MACAddress, resolutionStrategy: IPResolutionStrategy = .dhcp, secondsToWait: UInt16 = 0, controlSocketURL: URL? = nil) async throws -> IPv4Address? {
    let waitUntil = Calendar.current.date(byAdding: .second, value: Int(secondsToWait), to: Date.now)!

    repeat {
@@ -64,6 +64,14 @@ struct IP: AsyncParsableCommand {
        if let leases = try Leases(), let ip = leases.ResolveMACAddress(macAddress: vmMACAddress) {
          return ip
        }
+      case .agent:
+        guard let controlSocketURL = controlSocketURL else {
+          throw RuntimeError.Generic("Cannot perform IP resolution via Tart Guest Agent when control socket URL is not set")
+        }
+
+        if let ip = try await AgentResolver.ResolveIP(controlSocketURL) {
+          return ip
+        }
      }

      // wait a second
@@ -320,9 +320,6 @@ struct Run: AsyncParsableCommand {
      if !(config.platform is PlatformSuspendable) {
        throw ValidationError("You can only suspend macOS VMs")
      }
-      if dir.count > 0 {
-        throw ValidationError("Suspending VMs with shared directories is not supported")
-      }

      if noTrackpad {
        throw ValidationError("--no-trackpad cannot be used with --suspendable")
@@ -348,6 +345,12 @@ struct Run: AsyncParsableCommand {
    let localStorage = VMStorageLocal()
    let vmDir = try localStorage.open(name)

+    // Validate disk format support
+    let vmConfig = try VMConfig(fromURL: vmDir.configURL)
+    if !vmConfig.diskFormat.isSupported {
+      throw ValidationError("Disk format '\(vmConfig.diskFormat.rawValue)' is not supported on this system.")
+    }
+
    let storageLock = try FileLock(lockURL: Config().tartHomeDir)
    try storageLock.lock()
    // check if there is a running VM with the same MAC address
@@ -489,6 +492,12 @@ struct Run: AsyncParsableCommand {
          }
        }

+        if #available(macOS 14, *) {
+          Task {
+            try await ControlSocket(vmDir.controlSocketURL).run()
+          }
+        }
+
        try await vm!.run()

        if let vncImpl = vncImpl {
@@ -0,0 +1,89 @@
+import Foundation
+import Network
+import os.log
+import NIO
+import NIOPosix
+
+@available(macOS 14, *)
+class ControlSocket {
+  let controlSocketURL: URL
+  let vmPort: UInt32
+  let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+  let logger: os.Logger = os.Logger(subsystem: "org.cirruslabs.tart.control-socket", category: "network")
+
+  init(_ controlSocketURL: URL, vmPort: UInt32 = 8080) {
+    self.controlSocketURL = controlSocketURL
+    self.vmPort = vmPort
+  }
+
+  func run() async throws {
+    // Remove control socket file from previous "tart run" invocations,
+    // if any, otherwise we may get the "address already in use" error
+    try? FileManager.default.removeItem(atPath: controlSocketURL.path())
+
+    let serverChannel = try await ServerBootstrap(group: eventLoopGroup)
+      .bind(unixDomainSocketPath: controlSocketURL.path()) { childChannel in
+        childChannel.eventLoop.makeCompletedFuture {
+          return try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+            wrappingChannelSynchronously: childChannel
+          )
+        }
+      }
+
+    try await withThrowingDiscardingTaskGroup { group in
+      try await serverChannel.executeThenClose { serverInbound in
+        for try await clientChannel in serverInbound {
+          group.addTask {
+            try await self.handleClient(clientChannel)
+          }
+        }
+      }
+    }
+  }
+
+  func handleClient(_ clientChannel: NIOAsyncChannel<ByteBuffer, ByteBuffer>) async throws {
+    self.logger.info("received new control socket connection from a client")
+
+    try await clientChannel.executeThenClose { clientInbound, clientOutbound in
+      self.logger.info("dialing to VM on port \(self.vmPort)...")
+
+      do {
+        guard let vmConnection = try await vm?.connect(toPort: self.vmPort) else {
+          throw RuntimeError.VMSocketFailed(self.vmPort, "VM is not running")
+        }
+
+        self.logger.info("running control socket proxy")
+
+        let vmChannel = try await ClientBootstrap(group: eventLoopGroup).withConnectedSocket(vmConnection.fileDescriptor) { childChannel in
+          childChannel.eventLoop.makeCompletedFuture {
+            try NIOAsyncChannel<ByteBuffer, ByteBuffer>(
+              wrappingChannelSynchronously: childChannel
+            )
+          }
+        }
+
+        try await vmChannel.executeThenClose { (vmInbound, vmOutbound) in
+          try await withThrowingDiscardingTaskGroup { group in
+            // Proxy data from a client (e.g. "tart exec") to a VM
+            group.addTask {
+              for try await message in clientInbound {
+                try await vmOutbound.write(message)
+              }
+            }
+
+            // Proxy data from a VM to a client (e.g. "tart exec")
+            group.addTask {
+              for try await message in vmInbound {
+                try await clientOutbound.write(message)
+              }
+            }
+          }
+        }
+
+        self.logger.info("control socket client disconnected")
+      } catch (let error) {
+        self.logger.error("control socket connection failed: \(error)")
+      }
+    }
+  }
+}
@@ -0,0 +1,43 @@
+import Foundation
+import ArgumentParser
+
+enum DiskImageFormat: String, CaseIterable, Codable {
+  case raw = "raw"
+  case asif = "asif"
+
+  var displayName: String {
+    switch self {
+    case .raw:
+      return "RAW"
+    case .asif:
+      return "ASIF (Apple Sparse Image Format)"
+    }
+  }
+
+
+  /// Check if the format is supported on the current system
+  var isSupported: Bool {
+    switch self {
+    case .raw:
+      return true
+    case .asif:
+      if #available(macOS 15, *) {
+        return true
+      } else {
+        return false
+      }
+    }
+  }
+
+
+}
+
+extension DiskImageFormat: ExpressibleByArgument {
+  init?(argument: String) {
+    self.init(rawValue: argument.lowercased())
+  }
+
+  static var allValueStrings: [String] {
+    return allCases.map { $0.rawValue }
+  }
+}
@@ -0,0 +1,42 @@
+import Foundation
+import Network
+import NIOPosix
+import GRPC
+import Cirruslabs_TartGuestAgent_Apple_Swift
+import Cirruslabs_TartGuestAgent_Grpc_Swift
+
+class AgentResolver {
+  static func ResolveIP(_ controlSocketURL: URL) async throws -> IPv4Address? {
+    do {
+      return try await resolveIP(controlSocketURL)
+    } catch let error as GRPCConnectionPoolError {
+      return nil
+    }
+  }
+
+  private static func resolveIP(_ controlSocketURL: URL) async throws -> IPv4Address? {
+    // Create a gRPC channel connected to the VM's control socket
+    let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+    defer {
+      try! group.syncShutdownGracefully()
+    }
+
+    let channel = try GRPCChannelPool.with(
+      target: .unixDomainSocket(controlSocketURL.path()),
+      transportSecurity: .plaintext,
+      eventLoopGroup: group,
+    )
+    defer {
+      try! channel.close().wait()
+    }
+
+    // Invoke ResolveIP() gRPC method
+    let callOptions = CallOptions(timeLimit: .timeout(.seconds(1)))
+    let agentAsyncClient = AgentAsyncClient(channel: channel)
+    let resolveIPCall = agentAsyncClient.makeResolveIpCall(ResolveIPRequest(), callOptions: callOptions)
+
+    let response = try await resolveIPCall.response
+
+    return IPv4Address(response.ip)
+  }
+}
@@ -14,6 +14,9 @@ let nvramMediaType = "application/vnd.cirruslabs.tart.nvram.v1"
 let uncompressedDiskSizeAnnotation = "org.cirruslabs.tart.uncompressed-disk-size"
 let uploadTimeAnnotation = "org.cirruslabs.tart.upload-time"

+// Manifest labels
+let diskFormatLabel = "org.cirruslabs.tart.disk.format"
+
 // Layer annotations
 let uncompressedSizeAnnotation = "org.cirruslabs.tart.uncompressed-size"
 let uncompressedContentDigestAnnotation = "org.cirruslabs.tart.uncompressed-content-digest"
@@ -18,6 +18,7 @@ struct Root: AsyncParsableCommand {
      Login.self,
      Logout.self,
      IP.self,
+      Exec.self,
      Pull.self,
      Push.self,
      Import.self,
@@ -30,39 +31,6 @@ struct Root: AsyncParsableCommand {
    ])

  public static func main() async throws {
-    // Initialize Sentry
-    if let dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"] {
-      SentrySDK.start { options in
-        options.dsn = dsn
-        options.releaseName = CI.release
-        options.tracesSampleRate = Float(
-          ProcessInfo.processInfo.environment["SENTRY_TRACES_SAMPLE_RATE"] ?? "1.0"
-        ) as NSNumber?
-
-        // By default only 5XX are captured
-        // Let's capture everything but 401 (unauthorized)
-        options.enableCaptureFailedRequests = true
-        options.failedRequestStatusCodes = [
-          HttpStatusCodeRange(min: 400, max: 400),
-          HttpStatusCodeRange(min: 402, max: 599)
-        ]
-      }
-    }
-    defer { SentrySDK.flush(timeout: 2.seconds.timeInterval) }
-
-    SentrySDK.configureScope { scope in
-      scope.setExtra(value: ProcessInfo.processInfo.arguments, key: "Command-line arguments")
-    }
-
-    // Enrich future events with Cirrus CI-specific tags
-    if let tags = ProcessInfo.processInfo.environment["CIRRUS_SENTRY_TAGS"] {
-      SentrySDK.configureScope { scope in
-        for (key, value) in tags.split(separator: ",").compactMap({ parseCirrusSentryTag($0) }) {
-          scope.setTag(value: value, key: key)
-        }
-      }
-    }
-
    // Add commands that are only available on specific macOS versions
    if #available(macOS 14, *) {
      configuration.subcommands.append(Suspend.self)
@@ -82,10 +50,43 @@ struct Root: AsyncParsableCommand {
    // Set line-buffered output for stdout
    setlinebuf(stdout)

-    // Parse and run command
    do {
+      // Parse command
      var command = try parseAsRoot()

+      // Initialize Sentry
+      if let dsn = ProcessInfo.processInfo.environment["SENTRY_DSN"] {
+        SentrySDK.start { options in
+          options.dsn = dsn
+          options.releaseName = CI.release
+          options.tracesSampleRate = Float(
+            ProcessInfo.processInfo.environment["SENTRY_TRACES_SAMPLE_RATE"] ?? "1.0"
+          ) as NSNumber?
+
+          // By default only 5XX are captured
+          // Let's capture everything but 401 (unauthorized)
+          options.enableCaptureFailedRequests = true
+          options.failedRequestStatusCodes = [
+            HttpStatusCodeRange(min: 400, max: 400),
+            HttpStatusCodeRange(min: 402, max: 599)
+          ]
+        }
+      }
+      defer { SentrySDK.flush(timeout: 2.seconds.timeInterval) }
+
+      SentrySDK.configureScope { scope in
+        scope.setExtra(value: ProcessInfo.processInfo.arguments, key: "Command-line arguments")
+      }
+
+      // Enrich future events with Cirrus CI-specific tags
+      if let tags = ProcessInfo.processInfo.environment["CIRRUS_SENTRY_TAGS"] {
+        SentrySDK.configureScope { scope in
+          for (key, value) in tags.split(separator: ",").compactMap({ parseCirrusSentryTag($0) }) {
+            scope.setTag(value: value, key: key)
+          }
+        }
+      }
+
      // Run garbage-collection before each command (shouldn't take too long)
      if type(of: command) != type(of: Pull()) && type(of: command) != type(of: Clone()){
        do {
@@ -95,12 +96,18 @@ struct Root: AsyncParsableCommand {
        }
      }

+      // Run command
      if var asyncCommand = command as? AsyncParsableCommand {
        try await asyncCommand.run()
      } else {
        try command.run()
      }
    } catch {
+      // Not an error, just a custom exit code from "tart exec"
+      if let execCustomExitCodeError = error as? ExecCustomExitCodeError {
+        Foundation.exit(execCustomExitCodeError.exitCode)
+      }
+
      // Capture the error into Sentry
      SentrySDK.capture(error: error)
      SentrySDK.flush(timeout: 2.seconds.timeInterval)
@@ -0,0 +1,60 @@
+import Foundation
+import System
+
+struct State {
+  fileprivate let termios: termios
+}
+
+class Term {
+  static func IsTerminal() -> Bool {
+    var termios = termios()
+
+    return tcgetattr(FileHandle.standardInput.fileDescriptor, &termios) != -1
+  }
+
+  static func MakeRaw() throws -> State {
+    var termiosOrig = termios()
+
+    var ret = tcgetattr(FileHandle.standardInput.fileDescriptor, &termiosOrig)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to retrieve terminal parameters: \(details)")
+    }
+
+    var termiosRaw = termiosOrig
+    cfmakeraw(&termiosRaw)
+
+    ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termiosRaw)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+
+    return State(termios: termiosOrig)
+  }
+
+  static func Restore(_ state: State) throws {
+    var termios = state.termios
+
+    let ret = tcsetattr(FileHandle.standardInput.fileDescriptor, TCSANOW, &termios)
+    if ret == -1 {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to set terminal parameters: \(details)")
+    }
+  }
+
+  static func GetSize() throws -> (width: UInt16, height: UInt16) {
+    var winsize = winsize()
+
+    guard ioctl(STDOUT_FILENO, TIOCGWINSZ, &winsize) != -1 else {
+      let details = Errno(rawValue: CInt(errno))
+
+      throw RuntimeError.TerminalOperationFailed("failed to get terminal size: \(details)")
+    }
+
+    return (width: winsize.ws_col, height: winsize.ws_row)
+  }
+}
@@ -143,6 +143,7 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
      vmDir: VMDirectory,
      ipswURL: URL,
      diskSizeGB: UInt16,
+      diskFormat: DiskImageFormat = .raw,
      network: Network = NetworkShared(),
      additionalStorageDevices: [VZStorageDeviceConfiguration] = [],
      directorySharingDevices: [VZDirectorySharingDeviceConfiguration] = [],
@@ -175,14 +176,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
      _ = try VZMacAuxiliaryStorage(creatingStorageAt: vmDir.nvramURL, hardwareModel: requirements.hardwareModel)

      // Create disk
-      try vmDir.resizeDisk(diskSizeGB)
+      try vmDir.resizeDisk(diskSizeGB, format: diskFormat)

      name = vmDir.name
      // Create config
      config = VMConfig(
        platform: Darwin(ecid: VZMacMachineIdentifier(), hardwareModel: requirements.hardwareModel),
        cpuCountMin: requirements.minimumSupportedCPUCount,
-        memorySizeMin: requirements.minimumSupportedMemorySize
+        memorySizeMin: requirements.minimumSupportedMemorySize,
+        diskFormat: diskFormat
      )
      // allocate at least 4 CPUs because otherwise VMs are frequently freezing
      try config.setCPU(cpuCount: max(4, requirements.minimumSupportedCPUCount))
@@ -224,15 +226,15 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
  #endif

  @available(macOS 13, *)
-  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16) async throws -> VM {
+  static func linux(vmDir: VMDirectory, diskSizeGB: UInt16, diskFormat: DiskImageFormat = .raw) async throws -> VM {
    // Create NVRAM
    _ = try VZEFIVariableStore(creatingVariableStoreAt: vmDir.nvramURL)

    // Create disk
-    try vmDir.resizeDisk(diskSizeGB)
+    try vmDir.resizeDisk(diskSizeGB, format: diskFormat)

    // Create config
-    let config = VMConfig(platform: Linux(), cpuCountMin: 4, memorySizeMin: 4096 * 1024 * 1024)
+    let config = VMConfig(platform: Linux(), cpuCountMin: 4, memorySizeMin: 4096 * 1024 * 1024, diskFormat: diskFormat)
    try config.save(toURL: vmDir.configURL)

    return try VM(vmDir: vmDir)
@@ -248,6 +250,19 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    }
  }

+  @MainActor
+  func connect(toPort: UInt32) async throws -> VZVirtioSocketConnection {
+    guard let socketDevice = virtualMachine.socketDevices.first else {
+      throw RuntimeError.VMSocketFailed(toPort, ", VM has no socket devices configured")
+    }
+
+    guard let virtioSocketDevice = socketDevice as? VZVirtioSocketDevice else {
+      throw RuntimeError.VMSocketFailed(toPort, ", expected VM's first socket device to have a type of VZVirtioSocketDevice, got \(type(of: socketDevice)) instead")
+    }
+
+    return try await virtioSocketDevice.connect(toPort: toPort)
+  }
+
  func run() async throws {
    do {
      try await sema.waitUnlessCancelled()
@@ -399,15 +414,16 @@ class VM: NSObject, VZVirtualMachineDelegate, ObservableObject {
    //
    // A dummy console device useful for implementing
    // host feature checks in the guest agent software.
-    if !suspendable {
-      let consolePort = VZVirtioConsolePortConfiguration()
-      consolePort.name = "tart-version-\(CI.version)"
+    let consolePort = VZVirtioConsolePortConfiguration()
+    consolePort.name = "tart-version-\(CI.version)"

-      let consoleDevice = VZVirtioConsoleDeviceConfiguration()
-      consoleDevice.ports[0] = consolePort
+    let consoleDevice = VZVirtioConsoleDeviceConfiguration()
+    consoleDevice.ports[0] = consolePort

-      configuration.consoleDevices.append(consoleDevice)
-    }
+    configuration.consoleDevices.append(consoleDevice)
+
+    // Socket device
+    configuration.socketDevices = [VZVirtioSocketDeviceConfiguration()]

    try configuration.validate()

@@ -25,6 +25,7 @@ enum CodingKeys: String, CodingKey {
  case macAddress
  case display
  case displayRefit
+  case diskFormat

  // macOS-specific keys
  case ecid
@@ -54,12 +55,14 @@ struct VMConfig: Codable {
  var macAddress: VZMACAddress
  var display: VMDisplayConfig = VMDisplayConfig()
  var displayRefit: Bool?
+  var diskFormat: DiskImageFormat = .raw

  init(
    platform: Platform,
    cpuCountMin: Int,
    memorySizeMin: UInt64,
-    macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered()
+    macAddress: VZMACAddress = VZMACAddress.randomLocallyAdministered(),
+    diskFormat: DiskImageFormat = .raw
  ) {
    self.os = platform.os()
    self.arch = CurrentArchitecture()
@@ -67,6 +70,7 @@ struct VMConfig: Codable {
    self.macAddress = macAddress
    self.cpuCountMin = cpuCountMin
    self.memorySizeMin = memorySizeMin
+    self.diskFormat = diskFormat
    cpuCount = cpuCountMin
    memorySize = memorySizeMin
  }
@@ -124,6 +128,8 @@ struct VMConfig: Codable {

    display = try container.decodeIfPresent(VMDisplayConfig.self, forKey: .display) ?? VMDisplayConfig()
    displayRefit = try container.decodeIfPresent(Bool.self, forKey: .displayRefit)
+    let diskFormatString = try container.decodeIfPresent(String.self, forKey: .diskFormat) ?? "raw"
+    diskFormat = DiskImageFormat(rawValue: diskFormatString) ?? .raw
  }

  func encode(to encoder: Encoder) throws {
@@ -142,6 +148,7 @@ struct VMConfig: Codable {
    if let displayRefit = displayRefit {
      try container.encode(displayRefit, forKey: .displayRefit)
    }
+    try container.encode(diskFormat.rawValue, forKey: .diskFormat)
  }

  mutating func setCPU(cpuCount: Int) throws {
@@ -92,6 +92,10 @@ extension VMDirectory {

    // Read VM's config and push it as blob
    let config = try VMConfig(fromURL: configURL)
+
+    // Add disk format label automatically
+    var labels = labels
+    labels[diskFormatLabel] = config.diskFormat.rawValue
    let configJSON = try JSONEncoder().encode(config)
    defaultLogger.appendNewLine("pushing config...")
    let configDigest = try await registry.pushBlob(fromData: configJSON, chunkSizeMb: chunkSizeMb)
@@ -2,6 +2,25 @@ import Foundation
 import Virtualization
 import CryptoKit

+// MARK: - Disk Image Info Structures
+struct DiskImageInfo: Codable {
+  let sizeInfo: SizeInfo?
+  let size: UInt64?
+
+  enum CodingKeys: String, CodingKey {
+    case sizeInfo = "Size Info"
+    case size = "Size"
+  }
+}
+
+struct SizeInfo: Codable {
+  let totalBytes: UInt64?
+
+  enum CodingKeys: String, CodingKey {
+    case totalBytes = "Total Bytes"
+  }
+}
+
 struct VMDirectory: Prunable {
  enum State: String {
    case Running = "running"
@@ -26,6 +45,9 @@ struct VMDirectory: Prunable {
  var manifestURL: URL {
    baseURL.appendingPathComponent("manifest.json")
  }
+  var controlSocketURL: URL {
+    baseURL.appendingPathComponent("control.sock")
+  }

  var explicitlyPulledMark: URL {
    baseURL.appendingPathComponent(".explicitly-pulled")
@@ -139,14 +161,34 @@ struct VMDirectory: Prunable {
    try vmConfig.save(toURL: configURL)
  }

-  func resizeDisk(_ sizeGB: UInt16) throws {
-    if !FileManager.default.fileExists(atPath: diskURL.path) {
-      FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
-    }
+  func resizeDisk(_ sizeGB: UInt16, format: DiskImageFormat = .raw) throws {
+    let diskExists = FileManager.default.fileExists(atPath: diskURL.path)

+    if diskExists {
+      // Existing disk - resize it
+      try resizeExistingDisk(sizeGB)
+    } else {
+      // New disk - create it with the specified format
+      try createDisk(sizeGB: sizeGB, format: format)
+    }
+  }
+
+  private func resizeExistingDisk(_ sizeGB: UInt16) throws {
+    // Check if this is an ASIF disk by reading the VM config
+    let vmConfig = try VMConfig(fromURL: configURL)
+
+    if vmConfig.diskFormat == .asif {
+      try resizeASIFDisk(sizeGB)
+    } else {
+      try resizeRawDisk(sizeGB)
+    }
+  }
+
+  private func resizeRawDisk(_ sizeGB: UInt16) throws {
    let diskFileHandle = try FileHandle.init(forWritingTo: diskURL)
    let currentDiskFileLength = try diskFileHandle.seekToEnd()
    let desiredDiskFileLength = UInt64(sizeGB) * 1000 * 1000 * 1000
+
    if desiredDiskFileLength < currentDiskFileLength {
      let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentDiskFileLength))
      let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredDiskFileLength))
@@ -158,6 +200,157 @@ struct VMDirectory: Prunable {
    try diskFileHandle.close()
  }

+  private func resizeASIFDisk(_ sizeGB: UInt16) throws {
+    guard let diskutilURL = resolveBinaryPath("diskutil") else {
+      throw RuntimeError.FailedToResizeDisk("diskutil not found in PATH")
+    }
+
+    // First, get current disk image info to check current size
+    let infoProcess = Process()
+    infoProcess.executableURL = diskutilURL
+    infoProcess.arguments = ["image", "info", "--plist", diskURL.path]
+
+    let infoPipe = Pipe()
+    infoProcess.standardOutput = infoPipe
+    infoProcess.standardError = infoPipe
+
+    do {
+      try infoProcess.run()
+      infoProcess.waitUntilExit()
+
+      let infoData = infoPipe.fileHandleForReading.readDataToEndOfFile()
+
+      if infoProcess.terminationStatus != 0 {
+        let output = String(data: infoData, encoding: .utf8) ?? "Unknown error"
+        throw RuntimeError.FailedToResizeDisk("Failed to get ASIF disk info: \(output)")
+      }
+
+      // Parse the plist using PropertyListDecoder
+      do {
+        let diskImageInfo = try PropertyListDecoder().decode(DiskImageInfo.self, from: infoData)
+
+        // Extract current size from the decoded structure
+        var currentSizeBytes: UInt64?
+
+        // Try to get size from Size Info -> Total Bytes first
+        if let totalBytes = diskImageInfo.sizeInfo?.totalBytes {
+          currentSizeBytes = totalBytes
+        } else if let size = diskImageInfo.size {
+          // Fallback to top-level Size field
+          currentSizeBytes = size
+        }
+
+        guard let currentSizeBytes = currentSizeBytes else {
+          throw RuntimeError.FailedToResizeDisk("Could not find size information in disk image info")
+        }
+
+        let desiredSizeBytes = UInt64(sizeGB) * 1000 * 1000 * 1000
+
+        if desiredSizeBytes < currentSizeBytes {
+          let currentLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(currentSizeBytes))
+          let desiredLengthHuman = ByteCountFormatter().string(fromByteCount: Int64(desiredSizeBytes))
+          throw RuntimeError.InvalidDiskSize("new disk size of \(desiredLengthHuman) should be larger " +
+            "than the current disk size of \(currentLengthHuman)")
+        } else if desiredSizeBytes > currentSizeBytes {
+          // Resize the ASIF disk image using diskutil
+          try performASIFResize(sizeGB)
+        }
+        // If sizes are equal, no action needed
+      } catch let error as RuntimeError {
+        throw error
+      } catch {
+        let outputString = String(data: infoData, encoding: .utf8) ?? "Unable to decode output"
+        throw RuntimeError.FailedToResizeDisk("Failed to parse disk image info: \(error). Output: \(outputString)")
+      }
+    } catch {
+      throw RuntimeError.FailedToResizeDisk("Failed to get disk image info: \(error)")
+    }
+  }
+
+  private func performASIFResize(_ sizeGB: UInt16) throws {
+    guard let diskutilURL = resolveBinaryPath("diskutil") else {
+      throw RuntimeError.FailedToResizeDisk("diskutil not found in PATH")
+    }
+
+    let process = Process()
+    process.executableURL = diskutilURL
+    process.arguments = [
+      "image", "resize",
+      "--size", "\(sizeGB)G",
+      diskURL.path
+    ]
+
+    let pipe = Pipe()
+    process.standardOutput = pipe
+    process.standardError = pipe
+
+    do {
+      try process.run()
+      process.waitUntilExit()
+
+      let data = pipe.fileHandleForReading.readDataToEndOfFile()
+
+      if process.terminationStatus != 0 {
+        let output = String(data: data, encoding: .utf8) ?? "Unknown error"
+        throw RuntimeError.FailedToResizeDisk("Failed to resize ASIF disk image: \(output)")
+      }
+    } catch {
+      throw RuntimeError.FailedToResizeDisk("Failed to execute diskutil resize: \(error)")
+    }
+  }
+
+  private func createDisk(sizeGB: UInt16, format: DiskImageFormat) throws {
+    switch format {
+    case .raw:
+      try createRawDisk(sizeGB: sizeGB)
+    case .asif:
+      try createASIFDisk(sizeGB: sizeGB)
+    }
+  }
+
+  private func createRawDisk(sizeGB: UInt16) throws {
+    // Create traditional raw disk image
+    FileManager.default.createFile(atPath: diskURL.path, contents: nil, attributes: nil)
+
+    let diskFileHandle = try FileHandle.init(forWritingTo: diskURL)
+    let desiredDiskFileLength = UInt64(sizeGB) * 1000 * 1000 * 1000
+    try diskFileHandle.truncate(atOffset: desiredDiskFileLength)
+    try diskFileHandle.close()
+  }
+
+  private func createASIFDisk(sizeGB: UInt16) throws {
+    guard let diskutilURL = resolveBinaryPath("diskutil") else {
+      throw RuntimeError.FailedToCreateDisk("diskutil not found in PATH")
+    }
+
+    let process = Process()
+    process.executableURL = diskutilURL
+    process.arguments = [
+      "image", "create", "blank",
+      "--format", "ASIF",
+      "--size", "\(sizeGB)G",
+      "--volumeName", "Tart",
+      diskURL.path
+    ]
+
+    let pipe = Pipe()
+    process.standardOutput = pipe
+    process.standardError = pipe
+
+    do {
+      try process.run()
+      process.waitUntilExit()
+
+      if process.terminationStatus != 0 {
+        let data = pipe.fileHandleForReading.readDataToEndOfFile()
+        let output = String(data: data, encoding: .utf8) ?? "Unknown error"
+        throw RuntimeError.FailedToCreateDisk("Failed to create ASIF disk image: \(output)")
+      }
+    } catch {
+      throw RuntimeError.FailedToCreateDisk("Failed to execute diskutil: \(error)")
+    }
+  }
+
  func delete() throws {
    let lock = try lock()

@@ -49,6 +49,7 @@ extension Error {
 }

 enum RuntimeError : Error {
+  case Generic(_ message: String)
  case VMConfigurationError(_ message: String)
  case VMDoesNotExist(name: String)
  case VMMissingFiles(_ message: String)
@@ -59,6 +60,8 @@ enum RuntimeError : Error {
  case DiskAlreadyInUse(_ message: String)
  case FailedToOpenBlockDevice(_ path: String, _ explanation: String)
  case InvalidDiskSize(_ message: String)
+  case FailedToCreateDisk(_ message: String)
+  case FailedToResizeDisk(_ message: String)
  case FailedToUpdateAccessDate(_ message: String)
  case PIDLockFailed(_ message: String)
  case PIDLockMissing(_ message: String)
@@ -75,6 +78,8 @@ enum RuntimeError : Error {
  case SuspendFailed(_ message: String)
  case PullFailed(_ message: String)
  case VirtualMachineLimitExceeded(_ hint: String)
+  case VMSocketFailed(_ port: UInt32, _ explanation: String)
+  case TerminalOperationFailed(_ message: String)
 }

 protocol HasExitCode {
@@ -84,6 +89,8 @@ protocol HasExitCode {
 extension RuntimeError : CustomStringConvertible {
  public var description: String {
    switch self {
+    case .Generic(let message):
+      return message
    case .VMConfigurationError(let message):
      return message
    case .VMDoesNotExist(let name):
@@ -104,6 +111,10 @@ extension RuntimeError : CustomStringConvertible {
      return "failed to open block device \(path): \(explanation)"
    case .InvalidDiskSize(let message):
      return message
+    case .FailedToCreateDisk(let message):
+      return message
+    case .FailedToResizeDisk(let message):
+      return message
    case .FailedToUpdateAccessDate(let message):
      return message
    case .PIDLockFailed(let message):
@@ -136,6 +147,10 @@ extension RuntimeError : CustomStringConvertible {
      return message
    case .VirtualMachineLimitExceeded(let hint):
      return "The number of VMs exceeds the system limit\(hint)"
+    case .VMSocketFailed(let port, let explanation):
+      return "Failed to establish a VM socket connection to port \(port): \(explanation)"
+    case .TerminalOperationFailed(let message):
+      return message
    }
  }
 }
@@ -0,0 +1,67 @@
+import XCTest
+@testable import tart
+
+final class DiskImageFormatTests: XCTestCase {
+  func testRawFormatIsAlwaysSupported() throws {
+    XCTAssertTrue(DiskImageFormat.raw.isSupported)
+  }
+
+  func testASIFFormatSupport() throws {
+    // ASIF should be supported on macOS 15+
+    if #available(macOS 15, *) {
+      XCTAssertTrue(DiskImageFormat.asif.isSupported)
+    } else {
+      XCTAssertFalse(DiskImageFormat.asif.isSupported)
+    }
+  }
+
+  func testFormatFromString() throws {
+    XCTAssertEqual(DiskImageFormat(rawValue: "raw"), .raw)
+    XCTAssertEqual(DiskImageFormat(rawValue: "asif"), .asif)
+    XCTAssertNil(DiskImageFormat(rawValue: "invalid"))
+  }
+
+  func testCaseInsensitivity() throws {
+    XCTAssertEqual(DiskImageFormat(argument: "ASIF"), .asif) // case insensitive
+    XCTAssertEqual(DiskImageFormat(argument: "Raw"), .raw)  // case insensitive
+  }
+
+  func testAllValueStrings() throws {
+    let allValues = DiskImageFormat.allValueStrings
+    XCTAssertTrue(allValues.contains("raw"))
+    XCTAssertTrue(allValues.contains("asif"))
+    XCTAssertEqual(allValues.count, 2)
+  }
+
+  func testVMConfigDiskFormatSerialization() throws {
+    // Test that VMConfig properly serializes and deserializes disk format
+    let config = VMConfig(
+      platform: Linux(),
+      cpuCountMin: 2,
+      memorySizeMin: 1024 * 1024 * 1024,
+      diskFormat: .asif
+    )
+
+    XCTAssertEqual(config.diskFormat, .asif)
+
+    // Test JSON encoding/decoding
+    let encoder = JSONEncoder()
+    let data = try encoder.encode(config)
+
+    let decoder = JSONDecoder()
+    let decodedConfig = try decoder.decode(VMConfig.self, from: data)
+
+    XCTAssertEqual(decodedConfig.diskFormat, .asif)
+  }
+
+  func testVMConfigDefaultDiskFormat() throws {
+    // Test that VMConfig defaults to raw format
+    let config = VMConfig(
+      platform: Linux(),
+      cpuCountMin: 2,
+      memorySizeMin: 1024 * 1024 * 1024
+    )
+
+    XCTAssertEqual(config.diskFormat, .raw)
+  }
+}
@@ -9,4 +9,5 @@
 "MD033": false # Inline HTML
 "MD041": false # First line in file should be a top level heading
 "MD045": false # OK not to have a description for an image
-"MD046": false #  Code block style [Expected: fenced; Actual: indented]
+"MD046": false #  Code block style [Expected: fenced; Actual: indented]
+"MD059": false # It's OK to have "here" links
@@ -0,0 +1,72 @@
+---
+draft: false
+date: 2025-06-01
+search:
+  exclude: true
+authors:
+  - edigaryev
+categories:
+  - announcement
+---
+
+# Bridging the gaps with the Tart Guest Agent
+
+We're introducing a new improvement for the Tart usability experience: a [Tart Guest Agent](https://github.com/cirruslabs/tart-guest-agent).
+
+This agent provides automatic disk resizing, seamless clipboard sharing for macOS guests (a [long-awaited](https://github.com/cirruslabs/tart/issues/14) feature), and the ability to run commands, without SSH and networking, using the new `tart exec` command.
+
+As of recently, we include this agent in all non-vanilla Cirrus Labs images, so you likely won't need to do anything to benefit from these usability improvements.
+
+Read on to learn why we chose to implement the agent from scratch in Golang, and which features we plan to add next.
+
+<!-- more -->
+
+## Existing solutions
+
+Tart uses the Virtualization.Framework, and the latter implemented a SPICE client some time ago, however, one piece was missing: the agent that runs inside the guest.
+
+The original [SPICE `vdagent` implementation](https://gitlab.freedesktop.org/spice/linux/vd_agent) only supports Linux. While [a fork](https://github.com/utmapp/vd_agent) from the UTM project adds macOS support, the long-term viability of maintaining this fork without upstreaming changes is uncertain.
+
+Moreover, if we were to add some extra functionality (as we did), there would be more than one agent binary to ship and install, which complicates maintenance and makes it harder to explain to users why we need a bunch of agent binaries.
+
+In the end, we decided to go with our own solution, one that would easily accomodate future ideas.
+
+## Rolling our own agent
+
+After carefully inspecting the [`vdagent` protocol](https://www.spice-space.org/agent-protocol.html) we've realized that the clipboard sharing is actually a small subset of the whole protocol, making it relatively simple to implement.
+
+Thanks to Golang, we were able to implement the protocol much faster than we could have with a lower-level language like C (with all due respect), which requires manual memory management and complex event loops.
+
+As for the command execution via `tart exec`, we've decided to go with gRPC with a rather simple protocol:
+
+![An visualization of gRPC protocol used by the Tart Guest Agent](../images/tart-guest-agent-grpc-protocol.png)
+
+For each `tart exec` invocation a new gRPC `Exec` bidirectional stream is established with the agent running inside a VM. After the gRPC stream is established, `tart exec` sends a command to execute to the guest and streams the I/O. Once the command terminates, `tart exec` collects the process exit code and quits with exactly that exit code.
+
+Using gRPC simplifies `tart exec` implementation because of code generation and forms a nice bridge between the host and the guest which allows us to easily expand the protocol later down the road when we decide to introduce new features.
+
+Thanks to [gRPC Swift](https://github.com/grpc/grpc-swift), which is built on top of [SwiftNIO](https://github.com/apple/swift-nio), we get [`async/await`](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/) support for free, further simplifying the `tart exec` logic.
+
+As for the Tart Guest Agent, the final result is a Golang binary that [can be customized](https://github.com/cirruslabs/tart-guest-agent?tab=readme-ov-file#guest-agent-for-tart-vms) depending on the execution context:
+
+* launchd global daemon — runs as a privileged user (`root`), has no clipboard access
+    * `--resize-disk` — resizes the disk when there's a free space at the end of a disk (assuming that one previously ran `tart set --disk-size`)
+* launchd global agent — runs as a normal user (`admin`), has clipboard access
+    * `--run-vdagent` — clipboard sharing
+    * `--run-rpc` — `tart exec` and new functionality in the future
+
+We’ve also introduced `--run-daemon` (which implies `--resize-disk`) and `--run-agent` (which implies both `--run-vdagent` and `--run-rpc`) to help run the most appropriate functionality based on the given context.
+
+## Future plans
+
+First, we'd like to thank our paid clients, without whom this feature wouldn't have been possible.
+
+[Become one now](../../licensing.md) and enjoy higher allowances for Tart VMs and Orchard workers—while helping ensure that our roadmap aligns with your company's needs.
+
+In the near future we plan to implement:
+
+* Linux support — to provide seamless experience for Linux guests too
+* a new `tart ip` resolver — to provide a more robust IP retrieval facility for Linux guests, which often struggle to populate the host's ARP table with their network activity
+* `tart cp` command — to copy files from/to guest VMs
+
+Stay tuned, and feel free to send us feedback on [GitHub](https://github.com/cirruslabs/tart) and [Twitter](https://x.com/cirrus_labs)!
Author	SHA1	Message	Date
Fedor KorotkovandNikolay Edigaryev	3a6c5fb81d	feat: Add disk image format selection with ASIF support (#1094 ) * feat: Add disk image format selection with ASIF support * fixed goreleaser-pro * Fix ASIF disk format compatibility issues - Use .uncached caching mode for ASIF disks to avoid Virtualization framework compatibility issues - Improve caching mode selection logic for better maintainability - Fix compiler warning by changing var to let for attachment variable This resolves VM startup failures when using ASIF disk format by ensuring proper disk attachment configuration. * Update goreleaser installation to use tap-specific formula Change from 'brew install --cask goreleaser-pro' to 'brew install --cask goreleaser/tap/goreleaser-pro' for proper installation from the official goreleaser tap. * Remove VS Code configuration and add to gitignore - Remove .vscode/launch.json from repository - Add .vscode/ to .gitignore to prevent VS Code settings from being tracked * Implement ASIF disk resize using diskutil - Add support for resizing ASIF disk images using diskutil image resize - Detect disk format from VM config and route to appropriate resize method - Use diskutil image info to get current ASIF disk size and validate resize - Remove restriction that prevented ASIF disk resizing in Set command - Add FailedToResizeDisk error case for proper error handling - Maintain backward compatibility with raw disk resizing - Add comprehensive size validation to prevent data loss * Update Sources/tart/Commands/Create.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Update Sources/tart/DiskImageFormat.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Update Sources/tart/DiskImageFormat.swift Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com> * Fix test naming and remove redundant test cases - Rename testFormatArgument to testCaseInsensitivity for clarity - Remove redundant 'raw' and 'invalid' test cases already covered in testFormatFromString - Remove testFormatDescriptions test as it's not very useful Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152093510 * Remove canCreate property and simplify DiskImageFormat - Remove canCreate property since it's the same as isSupported - Remove description property entirely as it's not used - Fix displayName for RAW format (remove UDIF reference) - Remove checkDiskutilASIFSupport helper function Addresses review comments: - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152109450 - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152115610 - https://github.com/cirruslabs/tart/pull/1094#discussion_r2152124330 * Update Create command validation and help text - Simplify ArgumentParser help text to let it show possible values automatically - Remove canCreate validation since property was removed - Simplify error message for unsupported disk formats Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152113480 * Add disk format validation to Run command - Add validation to ensure ASIF disk format is supported on current system - Check disk format compatibility before attempting to run VM Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152109450 * Use proper namespaced constant for OCI label - Add diskFormatLabelAnnotation constant in Manifest.swift - Use org.cirruslabs.tart.disk.format namespace for consistency - Use variable shadowing instead of new variable name for labels Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152163515 * Remove special ASIF caching mode - Remove .uncached caching mode for ASIF disks - Use default caching logic for all disk formats - Testing shows .cached mode works fine on macOS 26.0 Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152133589 * Improve code structure in VMDirectory - Use guard let instead of nested if let for better readability - Reduce nesting in resizeASIFDisk function - Improve error handling flow Addresses review comment: https://github.com/cirruslabs/tart/pull/1094#discussion_r2152141916 * diskFormatLabel * reverted caching mode * Use PropertyListDecoder --------- Co-authored-by: Nikolay Edigaryev <edigaryev@gmail.com>	2025-06-19 18:27:30 +04:00
Nikolay Edigaryev	5793935317	tart ip: implement --resolver=agent (#1095 ) * tart ip: implement --resolver=agent * CI: fix GoReleaser installation	2025-06-19 13:07:06 +04:00
Nikolay Edigaryev	8dc8b644b2	tart exec: do not limit RPC call duration to 1 second	2025-06-11 20:15:18 +02:00
Nikolay Edigaryev	b625c04131	tart exec: make sure <name> goes after flags like -i and -t in --help (#1090 )	2025-06-11 21:58:30 +04:00
Nikolay Edigaryev	a0c03dcce6	docs: new "Bridging the gaps with the Tart Guest Agent" blog post (#1080 )	2025-06-01 19:54:45 -04:00
Nikolay Edigaryev	8539b8faae	Delay Sentry initialization until after we parse the CLI arguments (#1085 )	2025-05-30 17:24:19 +04:00
Nikolay Edigaryev	71159373e5	tart run: allow "--dir" with "--suspendable" (#1082 )	2025-05-30 17:24:09 +04:00
Fedor Korotkov	8248f19943	Update sentry (#1079 )	2025-05-28 23:06:10 +00:00
fedor	1cbc1e2cda	Suspendable VMs now support consoles	2025-05-28 17:09:54 -04:00
Nikolay Edigaryev	0187834c34	tart exec: explain that Tart Guest Agent is required (#1078 ) * tart exec: explain that Tart Guest Agent is required Also handle decrease the connection timeout to 1 second and provide a hint to the user. * execute() can be made private * Include error.localizedDescription	2025-05-27 12:57:56 +04:00
Nikolay Edigaryev	dfbdb5559c	Introduce "tart exec" command as an alternative to SSH (#1074 ) * Introduce "tart exec" command as an alternative to SSH * Simplify control socket machinery by using NIO async/await primitives * No reason to print the "vm" object directly, just refer to it as "VM" * Log to Apple’s Unified Logging System	2025-05-22 17:28:14 +04:00