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): add `lume cp` for host↔guest file transfer (#4896)
Francesco Bonaccibe898dc7fc00
diff --git a/docs/content/docs/lume/reference/cli/guest.mdx b/docs/content/docs/lume/reference/cli/guest.mdxindex 6552b3ad3e..9316b3b5db 100644--- a/docs/content/docs/lume/reference/cli/guest.mdx+++ b/docs/content/docs/lume/reference/cli/guest.mdx@@ -1,6 +1,6 @@---title: "Guest access"-description: "Prepare unattended setup, open SSH sessions and change SIP in a guest."+description: "Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest."---{/*@@ -14,6 +14,7 @@ description: "Prepare unattended setup, open SSH sessions and change SIP in a gu| --- | --- || [`lume setup`](#lume-setup) | Prepare unattended macOS setup. || [`lume ssh`](#lume-ssh) | Connect to a VM via SSH or execute commands remotely. |+| [`lume cp`](#lume-cp) | Copy files between the host and a VM. || [`lume sip`](#lume-sip) | Enable or disable System Integrity Protection on a macOS VM. |Every command also accepts the [global options](/lume/reference/cli#global-options).@@ -83,6 +84,42 @@ lume ssh my-vm "ls -la"lume ssh my-vm --timeout 0 "cd /app && npm test"```+## `lume cp`++Copy files between the host and a VM.++Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.++```text output+lume cp [OPTIONS] <source> <destination>+```++| Argument | Type | Default | Description |+| --- | --- | --- | --- |+| `<source>` | string | required | Source path. Use VM:PATH for a path inside a VM. |+| `<destination>` | string | required | Destination path. Use VM:PATH for a path inside a VM. |++| Flag | Short | Type | Default | Description |+| --- | --- | --- | --- | --- |+| <span id="lume-cp--user"></span>`--user` | `-u` | string | `lume` | SSH username. |+| <span id="lume-cp--password"></span>`--password` | `-p` | string | `lume` | SSH password. |+| <span id="lume-cp--storage"></span>`--storage` | | string | | Storage location name or path. |+| <span id="lume-cp--timeout"></span>`--timeout` | `-t` | integer | `600` | Transfer timeout in seconds (0 for no timeout). |+| <span id="lume-cp--recursive"></span>`--recursive` | `-r` | boolean | `false` | Copy directories recursively. |++**Examples**++```bash test="cli-shape" id="ref-lume-cp"+# Copy a host file into the VM+lume cp ./build.zip my-vm:/tmp/build.zip++# Copy a file out of the VM+lume cp my-vm:/tmp/out.log ./out.log++# Copy a directory into the VM+lume cp -r ./assets my-vm:/tmp/assets+```+## `lume sip`Enable or disable System Integrity Protection on a macOS VM.diff --git a/docs/content/docs/lume/reference/cli/index.mdx b/docs/content/docs/lume/reference/cli/index.mdxindex f9d9b10d50..68de920800 100644--- a/docs/content/docs/lume/reference/cli/index.mdx+++ b/docs/content/docs/lume/reference/cli/index.mdx@@ -51,12 +51,13 @@ Pull, push and convert VM images, find restore images, and prune the cache. [Ref### Guest access-Prepare unattended setup, open SSH sessions and change SIP in a guest. [Reference](/lume/reference/cli/guest).+Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest. [Reference](/lume/reference/cli/guest).| Command | Description || --- | --- || <span id="lume-setup"></span>[`lume setup`](/lume/reference/cli/guest#lume-setup) | Prepare unattended macOS setup. || <span id="lume-ssh"></span>[`lume ssh`](/lume/reference/cli/guest#lume-ssh) | Connect to a VM via SSH or execute commands remotely. |+| <span id="lume-cp"></span>[`lume cp`](/lume/reference/cli/guest#lume-cp) | Copy files between the host and a VM. || <span id="lume-sip"></span>[`lume sip`](/lume/reference/cli/guest#lume-sip) | Enable or disable System Integrity Protection on a macOS VM. |### Serverdiff --git a/docs/content/docs/lume/reference/index.mdx b/docs/content/docs/lume/reference/index.mdxindex 80eadfac3a..2ba88c6a62 100644--- a/docs/content/docs/lume/reference/index.mdx+++ b/docs/content/docs/lume/reference/index.mdx@@ -17,7 +17,7 @@ description: "Every lume command, HTTP endpoint and MCP tool, generated from the| [`lume`](/lume/reference/cli) | Synopsis, global options, exit codes and every command. || [VMs](/lume/reference/cli/vms) | Create, run, inspect, change, clone and delete virtual machines. || [Images](/lume/reference/cli/images) | Pull, push and convert VM images, find restore images, and prune the cache. |-| [Guest access](/lume/reference/cli/guest) | Prepare unattended setup, open SSH sessions and change SIP in a guest. |+| [Guest access](/lume/reference/cli/guest) | Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest. || [Server](/lume/reference/cli/server) | Run the HTTP API and MCP server, read its logs, and dump the CLI and API definitions. || [Configuration](/lume/reference/cli/config) | Storage locations, the image cache and telemetry settings. || [Updates](/lume/reference/cli/updates) | Check for, apply and choose the channel of Lume updates. |diff --git a/libs/lume/src/Commands/Cp.swift b/libs/lume/src/Commands/Cp.swiftnew file mode 100644index 0000000000..e68bb4b874--- /dev/null+++ b/libs/lume/src/Commands/Cp.swift@@ -0,0 +1,171 @@+import ArgumentParser+import Foundation++/// Copy files and directories between the host and a running VM.+///+/// `lume ssh` only runs remote commands, so moving a file into or out of a VM+/// previously required encoding it into the command line. `lume cp` performs the+/// transfer directly over the same SSH credentials `lume ssh` already uses.+struct Cp: AsyncParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "cp",+ abstract: "Copy files between the host and a VM",+ discussion: """+ Copy a file or directory between the host and a running VM over SSH.+ Exactly one of the source or destination is a VM path, written as+ VM:PATH (the same credentials as `lume ssh` are used).++ Examples:+ lume cp ./build.zip my-vm:/tmp/build.zip # host → guest+ lume cp my-vm:/tmp/out.log ./out.log # guest → host+ lume cp -r ./assets my-vm:/tmp/assets # copy a directory++ Directories are copied recursively automatically when the source is a+ host directory; pass --recursive for a recursive guest → host copy.+ """+ )++ @Argument(help: "Source path. Use VM:PATH for a path inside a VM.")+ var source: String++ @Argument(help: "Destination path. Use VM:PATH for a path inside a VM.")+ var destination: String++ @Option(name: [.short, .long], help: "SSH username (default: lume)")+ var user: String = "lume"++ @Option(name: [.short, .long], help: "SSH password (default: lume)")+ var password: String = "lume"++ @Option(name: .customLong("storage"), help: "Storage location name or path")+ var storage: String?++ @Flag(name: [.short, .long], help: "Copy directories recursively")+ var recursive: Bool = false++ @Option(+ name: [.short, .long],+ help: "Transfer timeout in seconds (0 for no timeout, default: 600)")+ var timeout: Int = 600++ @MainActor+ func run() async throws {+ TelemetryClient.shared.record(event: "lume_cp")++ let src = Self.parseEndpoint(source)+ let dst = Self.parseEndpoint(destination)++ switch (src, dst) {+ case (.local, .local):+ throw ValidationError(+ "Either the source or the destination must be a VM path (VM:PATH).")+ case (.remote, .remote):+ throw ValidationError(+ "Copying directly between two VMs is not supported; one path must be on the host.")+ case let (.local(localPath), .remote(vm, remotePath)):+ try transfer(+ vm: vm, localPath: localPath, remotePath: remotePath, upload: true)+ case let (.remote(vm, remotePath), .local(localPath)):+ try transfer(+ vm: vm, localPath: localPath, remotePath: remotePath, upload: false)+ }+ }++ @MainActor+ private func transfer(+ vm: String,+ localPath: String,+ remotePath: String,+ upload: Bool+ ) throws {+ var recursive = self.recursive++ if upload {+ var isDirectory: ObjCBool = false+ guard FileManager.default.fileExists(atPath: localPath, isDirectory: &isDirectory)+ else {+ throw CpError.localSourceNotFound(localPath)+ }+ // Directories need scp -r; enable it transparently.+ if isDirectory.boolValue {+ recursive = true+ }+ }++ let controller = LumeController()++ let vmDetails: VMDetails+ do {+ vmDetails = try controller.getDetails(name: vm, storage: storage)+ } catch {+ throw SSHError.vmNotFound(vm)+ }++ guard vmDetails.status == "running" else {+ throw SSHError.vmNotRunning(vm)+ }++ guard let ipAddress = vmDetails.ipAddress, !ipAddress.isEmpty else {+ throw SSHError.noIPAddress(vm)+ }++ guard vmDetails.sshAvailable == true else {+ throw SSHError.sshNotAvailable(vm)+ }++ let client = SystemSSHClient(+ host: ipAddress,+ port: 22,+ user: user,+ password: password+ )++ try client.copyFile(+ localPath: localPath,+ remotePath: remotePath,+ upload: upload,+ recursive: recursive,+ timeout: TimeInterval(timeout)+ )++ if upload {+ print("Copied \(localPath) to \(vm):\(remotePath)")+ } else {+ print("Copied \(vm):\(remotePath) to \(localPath)")+ }+ }++ /// A source or destination argument: either a host path or a `VM:PATH`.+ enum Endpoint: Equatable {+ case local(String)+ case remote(vm: String, path: String)+ }++ /// Classify an argument as a host path or a `VM:PATH` reference.+ ///+ /// Following scp's convention, the argument is a remote reference only when a+ /// colon appears before any path separator. This keeps host paths that+ /// contain a colon (e.g. `./a:b` or `/tmp/x:y`) local.+ static func parseEndpoint(_ raw: String) -> Endpoint {+ if let colon = raw.firstIndex(of: ":") {+ let prefix = raw[raw.startIndex..<colon]+ if !prefix.isEmpty && !prefix.contains("/") {+ let path = String(raw[raw.index(after: colon)...])+ return .remote(vm: String(prefix), path: path)+ }+ }+ return .local(raw)+ }+}++/// Errors specific to `lume cp`.+enum CpError: Error, LocalizedError {+ case localSourceNotFound(String)++ var errorDescription: String? {+ switch self {+ case .localSourceNotFound(let path):+ return "Source path '\(path)' does not exist on the host"+ }+ }+}diff --git a/libs/lume/src/SSH/SystemSSHClient.swift b/libs/lume/src/SSH/SystemSSHClient.swiftindex 793f712bca..2e828923e5 100644--- a/libs/lume/src/SSH/SystemSSHClient.swift+++ b/libs/lume/src/SSH/SystemSSHClient.swift@@ -354,6 +354,115 @@ public final class SystemSSHClient: Sendable {stagingNeedsCleanup = false}+ /// Copy a single file or directory between the host and the guest using system scp.+ ///+ /// - Parameters:+ /// - localPath: Path on the host.+ /// - remotePath: Path inside the guest.+ /// - upload: `true` to copy host → guest, `false` to copy guest → host.+ /// - recursive: Pass `-r` so directories are copied recursively.+ /// - timeout: Seconds before the transfer is aborted (`0` for no timeout).+ public func copyFile(+ localPath: String,+ remotePath: String,+ upload: Bool,+ recursive: Bool,+ timeout: TimeInterval = 600+ ) throws {+ let remoteEndpoint = remoteScpEndpoint(path: remotePath)+ let sources: [String]+ let destination: String+ if upload {+ sources = [localPath]+ destination = remoteEndpoint+ } else {+ sources = [remoteEndpoint]+ destination = localPath+ }++ let askpassPath = try createAskpassScript()+ defer { try? FileManager.default.removeItem(atPath: askpassPath) }++ let process = Process()+ process.executableURL = URL(fileURLWithPath: "/usr/bin/scp")+ process.arguments = fileCopyArguments(+ sources: sources,+ destination: destination,+ recursive: recursive+ )++ var environment = ProcessInfo.processInfo.environment+ environment["SSH_ASKPASS"] = askpassPath+ environment["SSH_ASKPASS_REQUIRE"] = "force"+ environment["DISPLAY"] = ":0"+ process.environment = environment+ process.standardInput = FileHandle.nullDevice+ process.standardOutput = FileHandle.nullDevice++ let stderrPipe = Pipe()+ process.standardError = stderrPipe++ try process.run()++ if timeout > 0 {+ DispatchQueue.global().asyncAfter(deadline: .now() + timeout) {+ if process.isRunning {+ process.terminate()+ }+ }+ }++ let stderrData = stderrPipe.fileHandleForReading.readDataToEndOfFile()+ process.waitUntilExit()++ guard process.terminationStatus == 0 else {+ let stderr = Self.filteredSSHOutput(stderrData)+ let message = stderr.isEmpty+ ? "scp exited with code \(process.terminationStatus)"+ : stderr+ throw SSHError.commandFailed(+ exitCode: process.terminationStatus,+ message: message+ )+ }+ }++ /// Build the `user@host:path` endpoint for scp, quoting the remote path so+ /// the guest shell preserves spaces and other special characters.+ func remoteScpEndpoint(path: String) -> String {+ "\(user)@\(host):\(Self.shellQuote(path))"+ }++ /// Build scp arguments for a general host ↔ guest file transfer.+ func fileCopyArguments(+ sources: [String],+ destination: String,+ recursive: Bool+ ) -> [String] {+ var args = [+ "-q",+ "-o", "StrictHostKeyChecking=no",+ "-o", "UserKnownHostsFile=/dev/null",+ "-o", "LogLevel=ERROR",+ "-o", "ConnectTimeout=10",+ "-o", "ServerAliveInterval=15",+ "-o", "ServerAliveCountMax=4",+ ]++ if recursive {+ args.append("-r")+ }++ if port != 22 {+ args += ["-P", "\(port)"]+ }++ args.append("--")+ args.append(contentsOf: sources)+ args.append(destination)+ return args+ }+/// Start an interactive SSH session using system sshpublic func interactive() throws {let askpassPath = try createAskpassScript()diff --git a/libs/lume/src/Utils/CommandDocExtractor.swift b/libs/lume/src/Utils/CommandDocExtractor.swiftindex 6c5a93c26c..6ba9754778 100644--- a/libs/lume/src/Utils/CommandDocExtractor.swift+++ b/libs/lume/src/Utils/CommandDocExtractor.swift@@ -128,6 +128,7 @@ enum CommandDocExtractor {shutdownDoc,restartDoc,sshDoc,+ cpDoc,sipDoc,ipswDoc,serveDoc,@@ -565,6 +566,35 @@ enum CommandDocExtractor {)}+ // MARK: - CP++ private static var cpDoc: CommandDoc {+ CommandDoc(+ name: "cp",+ abstract: "Copy files between the host and a VM",+ discussion: "Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.",+ arguments: [+ ArgumentDoc(name: "source", help: "Source path. Use VM:PATH for a path inside a VM", type: "String", isOptional: false),+ ArgumentDoc(name: "destination", help: "Destination path. Use VM:PATH for a path inside a VM", type: "String", isOptional: false),+ ],+ options: [+ OptionDoc(name: "user", shortName: "u", help: "SSH username", type: "String", defaultValue: "lume", isOptional: true),+ OptionDoc(name: "password", shortName: "p", help: "SSH password", type: "String", defaultValue: "lume", isOptional: true),+ OptionDoc(name: "storage", shortName: nil, help: "Storage location name or path", type: "String", defaultValue: nil, isOptional: true),+ OptionDoc(name: "timeout", shortName: "t", help: "Transfer timeout in seconds (0 for no timeout)", type: "Int", defaultValue: "600", isOptional: true),+ ],+ flags: [+ FlagDoc(name: "recursive", shortName: "r", help: "Copy directories recursively", defaultValue: false),+ ],+ subcommands: [],+ examples: [+ ExampleDoc("lume cp ./build.zip my-vm:/tmp/build.zip", "Copy a host file into the VM"),+ ExampleDoc("lume cp my-vm:/tmp/out.log ./out.log", "Copy a file out of the VM"),+ ExampleDoc("lume cp -r ./assets my-vm:/tmp/assets", "Copy a directory into the VM"),+ ]+ )+ }+// MARK: - SIPprivate static var sipDoc: CommandDoc {diff --git a/libs/lume/src/Utils/CommandRegistry.swift b/libs/lume/src/Utils/CommandRegistry.swiftindex 8d8b79ab76..b3cddeaa39 100644--- a/libs/lume/src/Utils/CommandRegistry.swift+++ b/libs/lume/src/Utils/CommandRegistry.swift@@ -18,6 +18,7 @@ enum CommandRegistry {Shutdown.self,Restart.self,SSH.self,+ Cp.self,Sip.self,IPSW.self,Serve.self,diff --git a/libs/lume/tests/CpCommandTests.swift b/libs/lume/tests/CpCommandTests.swiftnew file mode 100644index 0000000000..561e795151--- /dev/null+++ b/libs/lume/tests/CpCommandTests.swift@@ -0,0 +1,64 @@+import Foundation+import Testing++@testable import lume++@Test("cp parses VM:PATH references as remote endpoints")+func cpParsesRemoteEndpoints() {+ #expect(Cp.parseEndpoint("my-vm:/tmp/file") == .remote(vm: "my-vm", path: "/tmp/file"))+ #expect(Cp.parseEndpoint("my-vm:relative/path") == .remote(vm: "my-vm", path: "relative/path"))+ // Empty remote path (defaults to the guest home directory) is still remote.+ #expect(Cp.parseEndpoint("my-vm:") == .remote(vm: "my-vm", path: ""))+}++@Test("cp keeps host paths local even when they contain a colon")+func cpKeepsHostPathsLocal() {+ #expect(Cp.parseEndpoint("/tmp/file") == .local("/tmp/file"))+ #expect(Cp.parseEndpoint("./build.zip") == .local("./build.zip"))+ // A colon after a path separator is a local path, matching scp.+ #expect(Cp.parseEndpoint("/tmp/x:y") == .local("/tmp/x:y"))+ #expect(Cp.parseEndpoint("./a:b") == .local("./a:b"))+}++@Test("scp file-copy arguments target the host → guest direction")+func scpUploadArguments() throws {+ let client = SystemSSHClient(host: "192.168.64.24")+ let endpoint = client.remoteScpEndpoint(path: "/tmp/dest file.txt")+ let arguments = client.fileCopyArguments(+ sources: ["/tmp/source.txt"],+ destination: endpoint,+ recursive: false+ )+ let separator = try #require(arguments.firstIndex(of: "--"))++ #expect(!arguments.contains("-r"))+ #expect(arguments.contains("StrictHostKeyChecking=no"))+ #expect(arguments.contains("ServerAliveInterval=15"))+ // Remote path is shell-quoted so spaces survive the guest shell.+ #expect(endpoint == "[email protected]:'/tmp/dest file.txt'")+ #expect(Array(arguments[(separator + 1)...]) == ["/tmp/source.txt", endpoint])+}++@Test("scp file-copy arguments carry -r and a port override for recursive copies")+func scpRecursiveArgumentsWithPort() throws {+ let client = SystemSSHClient(+ host: "192.168.64.24",+ port: 2222,+ user: "lume",+ password: "secret"+ )+ let endpoint = client.remoteScpEndpoint(path: "/tmp/out.log")+ let arguments = client.fileCopyArguments(+ sources: [endpoint],+ destination: "/tmp/local.log",+ recursive: true+ )+ let separator = try #require(arguments.firstIndex(of: "--"))++ #expect(arguments.contains("-r"))+ #expect(arguments.contains("-P"))+ #expect(arguments.contains("2222"))+ // guest → host: the remote endpoint is the source, the host path the target.+ #expect(Array(arguments[(separator + 1)...]) == [endpoint, "/tmp/local.log"])+ #expect(endpoint == "[email protected]:'/tmp/out.log'")+}diff --git a/scripts/docs-generators/cli-specs/lume.json b/scripts/docs-generators/cli-specs/lume.jsonindex 5c861d210a..687946d301 100644--- a/scripts/docs-generators/cli-specs/lume.json+++ b/scripts/docs-generators/cli-specs/lume.json@@ -1000,6 +1000,80 @@],"subcommands": []},+ {+ "abstract": "Copy files between the host and a VM",+ "arguments": [+ {+ "help": "Source path. Use VM:PATH for a path inside a VM",+ "is_optional": false,+ "name": "source",+ "type": "String"+ },+ {+ "help": "Destination path. Use VM:PATH for a path inside a VM",+ "is_optional": false,+ "name": "destination",+ "type": "String"+ }+ ],+ "discussion": "Copies a file or directory between the host and a running VM over SSH, using the same credentials as `lume ssh`. Exactly one of the source or destination is a VM path, written as VM:PATH. Host directories are copied recursively automatically; pass --recursive for a recursive guest-to-host copy.",+ "examples": [+ {+ "command": "lume cp ./build.zip my-vm:/tmp/build.zip",+ "description": "Copy a host file into the VM"+ },+ {+ "command": "lume cp my-vm:/tmp/out.log ./out.log",+ "description": "Copy a file out of the VM"+ },+ {+ "command": "lume cp -r ./assets my-vm:/tmp/assets",+ "description": "Copy a directory into the VM"+ }+ ],+ "flags": [+ {+ "default_value": false,+ "help": "Copy directories recursively",+ "name": "recursive",+ "short_name": "r"+ }+ ],+ "name": "cp",+ "options": [+ {+ "default_value": "lume",+ "help": "SSH username",+ "is_optional": true,+ "name": "user",+ "short_name": "u",+ "type": "String"+ },+ {+ "default_value": "lume",+ "help": "SSH password",+ "is_optional": true,+ "name": "password",+ "short_name": "p",+ "type": "String"+ },+ {+ "help": "Storage location name or path",+ "is_optional": true,+ "name": "storage",+ "type": "String"+ },+ {+ "default_value": "600",+ "help": "Transfer timeout in seconds (0 for no timeout)",+ "is_optional": true,+ "name": "timeout",+ "short_name": "t",+ "type": "Int"+ }+ ],+ "subcommands": []+ },{"abstract": "Enable or disable System Integrity Protection on a macOS VM","arguments": [diff --git a/scripts/docs-generators/lume.ts b/scripts/docs-generators/lume.tsindex af868b3266..8dba1064e5 100644--- a/scripts/docs-generators/lume.ts+++ b/scripts/docs-generators/lume.ts@@ -80,8 +80,8 @@ export const CLI_GROUPS: CliGroup[] = [{slug: 'guest',title: 'Guest access',- summary: 'Prepare unattended setup, open SSH sessions and change SIP in a guest',- commands: ['setup', 'ssh', 'sip'],+ summary: 'Prepare unattended setup, open SSH sessions, copy files and change SIP in a guest',+ commands: ['setup', 'ssh', 'cp', 'sip'],},{slug: 'server',