Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mdx
index 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:
```bash
lume 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 the
preferred viewer; Lume uses its native viewer when the owning process supports
live 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.mdx
index 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 attach
diff --git a/libs/lume/src/Commands/DetachedRun.swift b/libs/lume/src/Commands/DetachedRun.swift
new file mode 100644
index 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.swift
index 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 {
@MainActor
func 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 telemetry
let 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.swift
index 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 = !noDisplay
diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swift
index 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.swift
new file mode 100644
index 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"))
+}