Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
import Darwin
import Foundation
// MARK: - VMDirectory
/// Manages a virtual machine's directory structure and files
/// Responsible for:
/// - Managing VM configuration files
/// - Handling disk operations
/// - Managing VM state and locking
/// - Providing access to VM-related paths
struct VMDirectory: Sendable {
// MARK: - Constants
private enum FileNames {
static let nvram = "nvram.bin"
static let disk = "disk.img"
static let config = "config.json"
static let sessions = "sessions.json"
static let provisioning = ".provisioning"
static let resizeMarker = "resize.lock.json"
static let diskBackup = "disk.img.pre-resize"
static let configBackup = "config.json.pre-resize"
static let savedState = "state.vzvmsave"
static let savedStateVsock = "state.vsock"
static let vsockSession = "vsock.json"
}
// MARK: - Properties
let dir: Path
let nvramPath: Path
let diskPath: Path
var runOwnerURL: URL { configPath.url.deletingLastPathComponent().appendingPathComponent(".run-owner.json") }
let configPath: Path
let sessionsPath: Path
let provisioningPath: Path
let resizeMarkerPath: Path
let diskBackupPath: Path
let configBackupPath: Path
let resizeGuardPath: Path
/// The VM's saved machine state (`lume suspend`), restored by the next run.
let statePath: Path
/// Present when the saved state was saved with a virtio socket device
/// (a run with host port forwards): a state restores only into the
/// devices it was saved with.
let stateVsockPath: Path
/// The running VM's host port forwards over vsock ([`VsockSession`]).
let vsockSessionPath: Path
/// The name of the VM directory
var name: String { dir.name }
// MARK: - Initialization
/// Creates a new VMDirectory instance
/// - Parameters:
/// - dir: The base directory path for the VM
init(_ dir: Path) {
self.dir = dir
self.nvramPath = dir.file(FileNames.nvram)
self.diskPath = dir.file(FileNames.disk)
self.configPath = dir.file(FileNames.config)
self.sessionsPath = dir.file(FileNames.sessions)
self.provisioningPath = dir.file(FileNames.provisioning)
self.resizeMarkerPath = dir.file(FileNames.resizeMarker)
self.diskBackupPath = dir.file(FileNames.diskBackup)
self.configBackupPath = dir.file(FileNames.configBackup)
self.statePath = dir.file(FileNames.savedState)
self.stateVsockPath = dir.file(FileNames.savedStateVsock)
self.vsockSessionPath = dir.file(FileNames.vsockSession)
self.resizeGuardPath = Path(
dir.url.deletingLastPathComponent()
.appendingPathComponent(".\(dir.name).resize.guard", isDirectory: false))
}
}
// MARK: - VM State Management
extension VMDirectory {
/// Checks if the VM directory is initialized (either fully ready or provisioning)
/// A VM is considered initialized if it has:
/// - All required files (config + disk + nvram), OR
/// - Config + provisioning marker (VM is being created)
func initialized() -> Bool {
let configExists = configPath.exists()
let diskExists = diskPath.exists()
let nvramExists = nvramPath.exists()
let provisioningExists = provisioningPath.exists()
// Fully initialized VM
if configExists && diskExists && nvramExists {
return true
}
// VM being provisioned (has config and provisioning marker)
if configExists && provisioningExists {
return true
}
return false
}
/// Checks if the VM directory exists
func exists() -> Bool {
dir.exists()
}
/// Whether the VM has a saved machine state its next run restores.
func hasSavedState() -> Bool {
statePath.exists()
}
/// Drops the saved machine state: once the VM booted or resumed, its
/// disk no longer matches the memory the state holds.
func discardSavedState() {
try? FileManager.default.removeItem(atPath: statePath.path)
try? FileManager.default.removeItem(atPath: stateVsockPath.path)
}
/// Whether the saved state was saved with a virtio socket device.
func savedStateHasVsock() -> Bool {
hasSavedState() && stateVsockPath.exists()
}
/// Records whether the state just saved has a virtio socket device.
func markSavedStateVsock(_ present: Bool) {
if present {
FileManager.default.createFile(atPath: stateVsockPath.path, contents: Data())
} else {
try? FileManager.default.removeItem(atPath: stateVsockPath.path)
}
}
/// The running VM's vsock forwards, when it was started with some.
func loadVsockSession() -> VsockSession? {
guard let data = try? Data(contentsOf: vsockSessionPath.url) else { return nil }
return try? JSONDecoder().decode(VsockSession.self, from: data)
}
func saveVsockSession(_ session: VsockSession) {
guard let data = try? JSONEncoder().encode(session) else { return }
try? data.write(to: vsockSessionPath.url, options: .atomic)
}
func clearVsockSession() {
try? FileManager.default.removeItem(atPath: vsockSessionPath.path)
}
}
// MARK: - Disk Management
extension VMDirectory {
/// Resizes the VM's disk to the specified size (grow-only).
/// - Parameter size: The new size in bytes
/// - Throws: VMDirectoryError if the disk operation fails or would shrink
/// the image (which silently truncates and corrupts the APFS tail).
func setDisk(_ size: UInt64) throws {
if !diskPath.exists() {
guard FileManager.default.createFile(atPath: diskPath.path, contents: nil) else {
throw VMDirectoryError.fileCreationFailed(diskPath.path)
}
}
let currentSize =
((try? FileManager.default.attributesOfItem(atPath: diskPath.path))?[.size]
as? NSNumber)?.uint64Value ?? 0
guard size >= currentSize else {
throw VMDirectoryError.diskOperationFailed(
"refusing to shrink disk from \(currentSize) to \(size) bytes")
}
let handle: FileHandle
do {
handle = try FileHandle(forWritingTo: diskPath.url)
} catch {
throw VMDirectoryError.diskOperationFailed(
"could not open \(diskPath.path): \(error.localizedDescription)")
}
defer { try? handle.close() }
do {
try handle.truncate(atOffset: size)
} catch {
throw VMDirectoryError.diskOperationFailed(
"truncate to \(size) bytes failed: \(error.localizedDescription)")
}
}
}
// MARK: - Resize Transaction Marker
extension VMDirectory {
func tryAcquireResizeGuard(exclusive: Bool) throws -> FileHandle? {
if !resizeGuardPath.exists() {
guard FileManager.default.createFile(atPath: resizeGuardPath.path, contents: Data()) else {
throw VMDirectoryError.fileCreationFailed(resizeGuardPath.path)
}
}
let handle = try FileHandle(forUpdating: resizeGuardPath.url)
let operation = exclusive ? (LOCK_EX | LOCK_NB) : (LOCK_SH | LOCK_NB)
guard flock(handle.fileDescriptor, operation) == 0 else {
try? handle.close()
return nil
}
return handle
}
/// Removes the resize guard file. Call it only after the VM directory
/// is gone, while holding the guard exclusively.
func removeResizeGuard() {
try? FileManager.default.removeItem(atPath: resizeGuardPath.path)
}
/// Loads the resize transaction marker if a resize is in progress.
func loadResizeMarker() throws -> ResizeMarker? {
guard resizeMarkerPath.exists() else {
return nil
}
do {
let data = try Data(contentsOf: resizeMarkerPath.url)
let marker = try JSONDecoder().decode(ResizeMarker.self, from: data)
guard marker.version == ResizeMarker.currentVersion else {
throw DiskResizeError.invalidResizeMarker("unsupported version \(marker.version)")
}
return marker
} catch let error as DiskResizeError {
throw error
} catch {
throw DiskResizeError.invalidResizeMarker(error.localizedDescription)
}
}
/// True if a disk resize transaction is currently armed.
func hasResizeMarker() -> Bool {
resizeMarkerPath.exists()
}
/// Persists (and fsyncs) the resize transaction marker.
func saveResizeMarker(_ marker: ResizeMarker) throws {
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
let data = try encoder.encode(marker)
let temporary = resizeMarkerPath.path + ".tmp"
guard FileManager.default.createFile(atPath: temporary, contents: data) else {
throw VMDirectoryError.fileCreationFailed(temporary)
}
let handle = try FileHandle(forWritingTo: URL(fileURLWithPath: temporary))
try handle.synchronize()
try handle.close()
guard Darwin.rename(temporary, resizeMarkerPath.path) == 0 else {
throw VMDirectoryError.diskOperationFailed(
"could not commit resize marker: \(String(cString: strerror(errno)))")
}
try syncDirectory()
}
/// Removes the resize transaction marker after the transaction resolves.
func clearResizeMarker() throws {
guard resizeMarkerPath.exists() else { return }
try FileManager.default.removeItem(atPath: resizeMarkerPath.path)
try syncDirectory()
}
private func syncDirectory() throws {
let directoryFD = Darwin.open(dir.path, O_RDONLY)
guard directoryFD >= 0 else {
throw VMDirectoryError.diskOperationFailed("could not open VM directory for sync")
}
defer { Darwin.close(directoryFD) }
guard Darwin.fsync(directoryFD) == 0 else {
throw VMDirectoryError.diskOperationFailed("could not sync VM directory")
}
}
}
// MARK: - Configuration Management
extension VMDirectory {
/// Saves the VM configuration to disk
/// - Parameter config: The configuration to save
/// - Throws: VMDirectoryError if the save operation fails
func saveConfig(_ config: VMConfig) throws {
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
do {
let data = try encoder.encode(config)
guard FileManager.default.createFile(atPath: configPath.path, contents: data) else {
throw VMDirectoryError.fileCreationFailed(configPath.path)
}
} catch {
throw VMDirectoryError.invalidConfigData
}
}
/// Loads the VM configuration from disk
/// - Returns: The loaded configuration
/// - Throws: VMDirectoryError if the load operation fails
func loadConfig() throws -> VMConfig {
guard let data = FileManager.default.contents(atPath: configPath.path) else {
throw VMDirectoryError.configNotFound
}
do {
let decoder = JSONDecoder()
return try decoder.decode(VMConfig.self, from: data)
} catch {
throw VMDirectoryError.invalidConfigData
}
}
}
// MARK: - VNC Session Management
/// Marker written while a VM session is running.
///
/// Legacy markers carry only `url` and `sharedDirectories`; both still decode
/// unchanged, and a VNC-backed session still encodes exactly those two fields.
/// A VNC-disabled session has no URL, so it omits `url` and instead records the
/// owning `lume run` process, which `get`/`list` verify against the config-file
/// run lock. Older Lume binaries fail to decode that marker and therefore
/// report the VM as stopped instead of acting on stale information.
struct VNCSession: Codable {
let url: String?
let sharedDirectories: [SharedDirectory]?
/// Absent on legacy markers, which always described a VNC-backed session.
let vncEnabled: Bool?
/// PID of the owning `lume run` process. Written only for VNC-disabled
/// sessions, which have no listening port to probe for liveness.
let pid: Int32?
/// Unix timestamp of when the session started.
let startedAt: Double?
/// A marker without `vncEnabled` predates the policy and described VNC.
var isVNCEnabled: Bool { vncEnabled ?? true }
init(
url: String?,
sharedDirectories: [SharedDirectory]? = nil,
vncEnabled: Bool? = nil,
pid: Int32? = nil,
startedAt: Double? = nil
) {
self.url = url
self.sharedDirectories = sharedDirectories
self.vncEnabled = vncEnabled
self.pid = pid
self.startedAt = startedAt
}
/// Marker for a run started with `--vnc disabled`.
static func vncDisabled(
pid: Int32,
startedAt: Double,
sharedDirectories: [SharedDirectory]? = nil
) -> VNCSession {
VNCSession(
url: nil,
sharedDirectories: sharedDirectories,
vncEnabled: false,
pid: pid,
startedAt: startedAt
)
}
}
extension VMDirectory {
/// Saves VNC session information to disk
/// - Parameters:
/// - session: The VNC session to save
/// - sharedDirectories: Optional array of shared directories to save with the session
/// - Throws: VMDirectoryError if the save operation fails
func saveSession(_ session: VNCSession) throws {
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
do {
let data = try encoder.encode(session)
guard FileManager.default.createFile(atPath: sessionsPath.path, contents: data) else {
throw VMDirectoryError.fileCreationFailed(sessionsPath.path)
}
} catch {
throw VMDirectoryError.invalidSessionData
}
}
/// Loads the VNC session information from disk
/// - Returns: The loaded VNC session
/// - Throws: VMDirectoryError if the load operation fails
func loadSession() throws -> VNCSession {
guard let data = FileManager.default.contents(atPath: sessionsPath.path) else {
throw VMDirectoryError.sessionNotFound
}
do {
let decoder = JSONDecoder()
return try decoder.decode(VNCSession.self, from: data)
} catch {
throw VMDirectoryError.invalidSessionData
}
}
/// Removes the VNC session information from disk
func clearSession() {
try? FileManager.default.removeItem(atPath: sessionsPath.path)
}
}
// MARK: - Provisioning Marker Management
/// Represents the provisioning state of a VM during long-running operations
struct ProvisioningMarker: Codable {
/// The type of operation being performed (e.g., "ipsw_install", "unattended_setup")
let operation: String
/// When the provisioning started (Unix timestamp)
let startedAt: Double
init(operation: String) {
self.operation = operation
self.startedAt = Date().timeIntervalSince1970
}
/// Returns true if provisioning started more than the specified hours ago
func isStale(hours: Double = 8.0) -> Bool {
let elapsed = Date().timeIntervalSince1970 - startedAt
return elapsed > (hours * 3600)
}
}
extension VMDirectory {
/// Saves a provisioning marker to indicate the VM is being created/configured
/// - Parameter marker: The provisioning marker containing operation type
/// - Throws: VMDirectoryError if the save operation fails
func saveProvisioningMarker(_ marker: ProvisioningMarker) throws {
let encoder = JSONEncoder()
encoder.outputFormatting = .prettyPrinted
do {
let data = try encoder.encode(marker)
guard FileManager.default.createFile(atPath: provisioningPath.path, contents: data) else {
throw VMDirectoryError.fileCreationFailed(provisioningPath.path)
}
} catch {
throw VMDirectoryError.fileCreationFailed(provisioningPath.path)
}
}
/// Loads the provisioning marker if it exists
/// - Returns: The provisioning marker, or nil if not in provisioning state
func loadProvisioningMarker() -> ProvisioningMarker? {
guard let data = FileManager.default.contents(atPath: provisioningPath.path) else {
return nil
}
return try? JSONDecoder().decode(ProvisioningMarker.self, from: data)
}
/// Removes the provisioning marker after creation completes
func clearProvisioningMarker() {
try? FileManager.default.removeItem(atPath: provisioningPath.path)
}
/// Checks if the VM is currently being provisioned
func isProvisioning() -> Bool {
provisioningPath.exists()
}
}
// MARK: - CustomStringConvertible
extension VMDirectory: CustomStringConvertible {
var description: String {
"VMDirectory(path: \(dir.path))"
}
}
extension VMDirectory {
func delete() throws {
try FileManager.default.removeItem(atPath: dir.path)
}
}
// MARK: - Lightweight VM Details
extension VMDirectory {
/// Get disk size information without loading the full VM
func getDiskSize() -> DiskSize {
do {
let resourceValues = try diskPath.url.resourceValues(forKeys: [
.totalFileAllocatedSizeKey,
.totalFileSizeKey,
])
if let allocated = resourceValues.totalFileAllocatedSize,
let total = resourceValues.totalFileSize {
return DiskSize(allocated: UInt64(allocated), total: UInt64(total))
}
} catch {
// Fallback to config value
}
// Try to get from config as fallback
if let config = try? loadConfig() {
return DiskSize(allocated: 0, total: config.diskSize ?? 0)
}
return DiskSize(allocated: 0, total: 0)
}
/// Build VMDetails directly without instantiating a full VM object
/// This is much faster for listing VMs since it avoids:
/// - Creating ImageLoader instances
/// - Initializing virtualization services
/// - Building the full VM object graph
///
/// - Parameters:
/// - locationName: The storage location name for this VM
/// - status: The VM status ("running", "stopped", or "provisioning")
/// - provisioningOperation: Optional operation type if status is "provisioning"
/// - vncUrl: Optional VNC URL if running
/// - ipAddress: Optional IP address if running
/// - sshAvailable: Optional SSH availability status
/// - Returns: VMDetails or nil if config cannot be loaded
func getDetails(
locationName: String,
status: String,
provisioningOperation: String? = nil,
vncUrl: String?,
ipAddress: String?,
sshAvailable: Bool? = nil,
downloadProgress: Double? = nil
) -> VMDetails? {
guard let config = try? loadConfig() else {
return nil
}
let vsockSession = status == "running" ? loadVsockSession() : nil
return VMDetails(
name: name,
os: config.os,
cpuCount: config.cpuCount ?? 0,
memorySize: config.memorySize ?? 0,
diskSize: getDiskSize(),
display: config.display.string,
status: status,
provisioningOperation: provisioningOperation,
vncUrl: vncUrl,
ipAddress: ipAddress,
sshAvailable: sshAvailable,
locationName: locationName,
sharedDirectories: nil,
networkMode: config.networkMode.description,
downloadProgress: downloadProgress,
machineIdentifier: config.machineIdentifier?.base64EncodedString(),
macAddress: config.macAddress,
savedState: hasSavedState(),
vsock: vsockSession.map { _ in true },
forwards: vsockSession.flatMap { $0.agent ? $0.forwards : nil }
)
}
}