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
feat(lume): support detached VM runs (#2647)
Francesco Bonacci9b7797a8a72f
diff --git a/docs/content/docs/how-to-guides/lume/manage-vms.mdx b/docs/content/docs/how-to-guides/lume/manage-vms.mdxindex 1ab316f3de..4d29c37808 100644--- a/docs/content/docs/how-to-guides/lume/manage-vms.mdx+++ b/docs/content/docs/how-to-guides/lume/manage-vms.mdx@@ -25,12 +25,20 @@ SSH availability when the VM is running.## Run, attach to, and stop a VM-Run Tahoe without automatically opening a viewer:+Run Tahoe without automatically opening a viewer. The owning process remains+attached to the terminal by default:```bashlume run macos-tahoe```+Use `--detach` to run it in the background. Lume prints its PID and writes logs+to `~/Library/Logs/lume/macos-tahoe.log` by default:++```bash+lume run macos-tahoe --detach+```+VNC remains active in the background. From another terminal, attach thepreferred viewer; Lume uses its native viewer when the owning process supportslive attachment and otherwise falls back to VNC:diff --git a/docs/content/docs/reference/lume/cli-reference.mdx b/docs/content/docs/reference/lume/cli-reference.mdxindex edf1f48018..517f473cac 100644--- a/docs/content/docs/reference/lume/cli-reference.mdx+++ b/docs/content/docs/reference/lume/cli-reference.mdx@@ -71,6 +71,7 @@ Run a virtual machine| `--registry` | String | ghcr.io | Container registry URL || `--organization` | String | trycua | Organization to pull from || `--display` | DisplayMode | none | Local viewer to open: vnc, native, or none. The VNC server remains available in every mode |+| `--log-file` | String | ~/Library/Logs/lume/{vm}.log | Log path for --detach || `--vnc-port` | Int | 0 | Port for VNC server (0 for auto-assign) || `--recovery-mode` | Bool | false | For macOS VMs only, boot in recovery mode || `--storage` | String | - | VM storage location to use |@@ -80,6 +81,7 @@ Run a virtual machine| Name | Default | Description || ---- | ------- | ----------- || `-d, --no-display` | false | Compatibility alias for --display none |+| `--detach` | false | Run the VM in the background and return immediately || `--clipboard` | false | Enable bidirectional clipboard sync via SSH. Automatic for native macOS display |### lume attachdiff --git a/libs/lume/src/Commands/DetachedRun.swift b/libs/lume/src/Commands/DetachedRun.swiftnew file mode 100644index 0000000000..745d187294--- /dev/null+++ b/libs/lume/src/Commands/DetachedRun.swift@@ -0,0 +1,115 @@+import Foundation++struct DetachedRunResult: Sendable {+ let processIdentifier: Int32+ let logURL: URL+}++enum DetachedRunError: LocalizedError {+ case executableUnavailable+ case launchFailed(String)++ var errorDescription: String? {+ switch self {+ case .executableUnavailable:+ return "Cannot locate the Lume executable for detached launch."+ case .launchFailed(let message):+ return "Failed to launch the detached VM process: \(message)"+ }+ }+}++enum DetachedVMRunner {+ static func launch(+ vmName: String,+ logPath: String?,+ arguments: [String] = CommandLine.arguments+ ) throws -> DetachedRunResult {+ guard let executableURL = Bundle.main.executableURL else {+ throw DetachedRunError.executableUnavailable+ }++ let logURL = resolvedLogURL(vmName: vmName, customPath: logPath)+ let fileManager = FileManager.default+ try fileManager.createDirectory(+ at: logURL.deletingLastPathComponent(),+ withIntermediateDirectories: true+ )+ if !fileManager.fileExists(atPath: logURL.path) {+ guard fileManager.createFile(atPath: logURL.path, contents: nil) else {+ throw DetachedRunError.launchFailed("Cannot create log file at \(logURL.path)")+ }+ }++ let logHandle = try FileHandle(forWritingTo: logURL)+ try logHandle.seekToEnd()++ let process = Process()+ process.executableURL = URL(fileURLWithPath: "/usr/bin/nohup")+ process.arguments = [executableURL.path] + childArguments(from: arguments)+ process.currentDirectoryURL = URL(+ fileURLWithPath: FileManager.default.currentDirectoryPath,+ isDirectory: true+ )+ process.environment = ProcessInfo.processInfo.environment+ process.standardInput = FileHandle.nullDevice+ process.standardOutput = logHandle+ process.standardError = logHandle++ do {+ try process.run()+ } catch {+ try? logHandle.close()+ throw DetachedRunError.launchFailed(error.localizedDescription)+ }+ try? logHandle.close()++ return DetachedRunResult(+ processIdentifier: process.processIdentifier,+ logURL: logURL+ )+ }++ static func childArguments(from arguments: [String]) -> [String] {+ var childArguments: [String] = []+ var iterator = Array(arguments.dropFirst()).makeIterator()+ while let argument = iterator.next() {+ switch argument {+ case "--detach":+ continue+ case "--log-file":+ _ = iterator.next()+ default:+ if !argument.hasPrefix("--log-file=") {+ childArguments.append(argument)+ }+ }+ }+ return childArguments+ }++ static func defaultLogURL(vmName: String) -> URL {+ let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "-_."))+ let safeName = String(+ vmName.unicodeScalars.map { allowed.contains($0) ? Character(String($0)) : "_" }+ )+ return FileManager.default.homeDirectoryForCurrentUser+ .appendingPathComponent("Library/Logs/lume", isDirectory: true)+ .appendingPathComponent("\(safeName).log")+ }++ private static func resolvedLogURL(vmName: String, customPath: String?) -> URL {+ guard let customPath else { return defaultLogURL(vmName: vmName) }+ let expanded = NSString(string: customPath).expandingTildeInPath+ if expanded.hasPrefix("/") {+ return URL(fileURLWithPath: expanded)+ }+ return URL(+ fileURLWithPath: expanded,+ relativeTo: URL(+ fileURLWithPath: FileManager.default.currentDirectoryPath,+ isDirectory: true+ )+ ).standardizedFileURL+ }+}diff --git a/libs/lume/src/Commands/Run.swift b/libs/lume/src/Commands/Run.swiftindex 48642c9166..8ff470fc29 100644--- a/libs/lume/src/Commands/Run.swift+++ b/libs/lume/src/Commands/Run.swift@@ -23,6 +23,18 @@ struct Run: AsyncParsableCommand {)var noDisplay: Bool = false+ @Flag(+ name: .customLong("detach"),+ help: "Run the VM in the background and return immediately"+ )+ var detach: Bool = false++ @Option(+ name: .customLong("log-file"),+ help: "Log path for --detach (default: ~/Library/Logs/lume/{vm}.log)"+ )+ var logFile: String?+@Option(name: [.customLong("shared-dir")],help:@@ -158,6 +170,13 @@ struct Run: AsyncParsableCommand {@MainActorfunc run() async throws {+ if detach {+ let result = try DetachedVMRunner.launch(vmName: name, logPath: logFile)+ print("Started '\(name)' in the background (PID \(result.processIdentifier)).")+ print("Log: \(result.logURL.path)")+ return+ }+// Record telemetrylet displayMode = DisplayMode.resolve(requested: display, noDisplay: noDisplay)TelemetryClient.shared.record(event: TelemetryEvent.run, properties: [diff --git a/libs/lume/src/Main.swift b/libs/lume/src/Main.swiftindex 28859eff0e..0c1836aacb 100644--- a/libs/lume/src/Main.swift+++ b/libs/lume/src/Main.swift@@ -113,7 +113,7 @@ extension Lume {showsNativeDisplayAtLaunch: Bool)? {let args = Array(CommandLine.arguments.dropFirst())- guard args.first == "run" else { return nil }+ guard args.first == "run", !args.contains("--detach") else { return nil }let noDisplay = args.contains("--no-display") || args.contains("-d")let usesNativeDisplay = !noDisplaydiff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swiftindex 001bb41290..a4e74cbf2c 100644--- a/libs/lume/src/Utils/CommandDocExtractor.swift+++ b/libs/lume/src/Utils/CommandDocExtractor.swift@@ -346,12 +346,14 @@ enum CommandDocExtractor {OptionDoc(name: "registry", shortName: nil, help: "Container registry URL", type: "String", defaultValue: "ghcr.io", isOptional: false),OptionDoc(name: "organization", shortName: nil, help: "Organization to pull from", type: "String", defaultValue: "trycua", isOptional: false),OptionDoc(name: "display", shortName: nil, help: "Local viewer to open: vnc, native, or none. The VNC server remains available in every mode", type: "DisplayMode", defaultValue: "none", isOptional: false),+ OptionDoc(name: "log-file", shortName: nil, help: "Log path for --detach", type: "String", defaultValue: "~/Library/Logs/lume/{vm}.log", isOptional: true),OptionDoc(name: "vnc-port", shortName: nil, help: "Port for VNC server (0 for auto-assign)", type: "Int", defaultValue: "0", isOptional: false),OptionDoc(name: "recovery-mode", shortName: nil, help: "For macOS VMs only, boot in recovery mode", type: "Bool", defaultValue: "false", isOptional: true),OptionDoc(name: "storage", shortName: nil, help: "VM storage location to use", type: "String", defaultValue: nil, isOptional: true),],flags: [FlagDoc(name: "no-display", shortName: "d", help: "Compatibility alias for --display none", defaultValue: false),+ FlagDoc(name: "detach", shortName: nil, help: "Run the VM in the background and return immediately", defaultValue: false),FlagDoc(name: "clipboard", shortName: nil, help: "Enable bidirectional clipboard sync via SSH. Automatic for native macOS display", defaultValue: false),],subcommands: []diff --git a/libs/lume/tests/DetachedRunTests.swift b/libs/lume/tests/DetachedRunTests.swiftnew file mode 100644index 0000000000..e294b0344b--- /dev/null+++ b/libs/lume/tests/DetachedRunTests.swift@@ -0,0 +1,34 @@+import ArgumentParser+import Foundation+import Testing++@testable import lume++@Test("Run parses detached mode and a custom log path")+func detachedRunParsing() throws {+ let command = try Run.parse([+ "test-vm", "--detach", "--log-file", "~/custom-lume.log",+ ])++ #expect(command.detach)+ #expect(command.logFile == "~/custom-lume.log")+}++@Test("Detached child arguments remove the detach flag without changing VM options")+func detachedChildArguments() {+ let arguments = DetachedVMRunner.childArguments(from: [+ "/path/to/lume", "run", "test-vm", "--detach", "--display", "native",+ "--log-file", "/tmp/vm.log", "--shared-dir", "/tmp/shared",+ ])++ #expect(+ arguments == [+ "run", "test-vm", "--display", "native", "--shared-dir", "/tmp/shared",+ ])+}++@Test("Detached runs use a per-VM log in the user Library")+func detachedDefaultLogPath() {+ let path = DetachedVMRunner.defaultLogURL(vmName: "example/vm:latest").path+ #expect(path.hasSuffix("/Library/Logs/lume/example_vm_latest.log"))+}