Add container copy/cp command for host-container file transfer

Sources/ContainerCommands/Application.swift

@@ -51,6 +51,7 @@ public struct Application: AsyncLoggableCommand {
             CommandGroup(
                 name: "Container",
                 subcommands: [
+                    ContainerCopy.self,
                     ContainerCreate.self,
                     ContainerDelete.self,
                     ContainerExec.self,

Sources/ContainerCommands/Container/ContainerCopy.swift

@@ -0,0 +1,99 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import ContainerAPIClient
+import ContainerResource
+import Containerization
+import ContainerizationError
+import Foundation
+
+extension Application {
+    public struct ContainerCopy: AsyncLoggableCommand {
+        enum PathRef {
+            case local(String)
+            case container(id: String, path: String)
+        }
+
+        static func parsePathRef(_ ref: String) throws -> PathRef {
+            let parts = ref.components(separatedBy: ":")
+            switch parts.count {
+            case 1:
+                return .local(ref)
+            case 2 where !parts[0].isEmpty && parts[1].starts(with: "/"):
+                return .container(id: parts[0], path: parts[1])
+            default:
+                throw ContainerizationError(.invalidArgument, message: "invalid path given: \(ref)")
+            }
+        }
+
+        public init() {}
+
+        public static let configuration = CommandConfiguration(
+            commandName: "copy",
+            abstract: "Copy files/folders between a container and the local filesystem",
+            aliases: ["cp"])
+
+        @OptionGroup()
+        public var logOptions: Flags.Logging
+
+        @Argument(help: "Source path (container:path or local path)")
+        var source: String
+
+        @Argument(help: "Destination path (container:path or local path)")
+        var destination: String
+
+        public func run() async throws {
+            let client = ContainerClient()
+            let srcRef = try Self.parsePathRef(source)
+            let dstRef = try Self.parsePathRef(destination)
+
+            switch (srcRef, dstRef) {
+            case (.container(let id, let path), .local(let localPath)):
+                let srcURL = URL(fileURLWithPath: path)
+                let destURL = URL(fileURLWithPath: localPath).standardizedFileURL
+                var isDirectory: ObjCBool = false
+                let exists = FileManager.default.fileExists(atPath: destURL.path, isDirectory: &isDirectory)
+                if localPath.hasSuffix("/") {
+                    guard exists && isDirectory.boolValue else {
+                        throw ContainerizationError(.invalidArgument, message: "destination path is not a directory: \(localPath)")
+                    }
+                }
+                let appendFilename = localPath.hasSuffix("/") || (exists && isDirectory.boolValue)
+                let finalDestURL = appendFilename ? destURL.appendingPathComponent(srcURL.lastPathComponent) : destURL
+                try await client.copyOut(id: id, source: srcURL, destination: finalDestURL)
+            case (.local(let localPath), .container(let id, let path)):
+                let srcURL = URL(fileURLWithPath: localPath).standardizedFileURL
+                var isDirectory: ObjCBool = false
+                guard FileManager.default.fileExists(atPath: srcURL.path, isDirectory: &isDirectory) else {
+                    throw ContainerizationError(.notFound, message: "source path does not exist: \(localPath)")
+                }
+                if localPath.hasSuffix("/") && !isDirectory.boolValue {
+                    throw ContainerizationError(.invalidArgument, message: "source path is not a directory: \(localPath)")
+                }
+                let containerDest = path.hasSuffix("/") ? path + srcURL.lastPathComponent : path
+                let destURL = URL(fileURLWithPath: containerDest)
+                try await client.copyIn(id: id, source: srcURL, destination: destURL)
+            case (.container, .container):
+                throw ContainerizationError(.invalidArgument, message: "copying between containers is not supported")
+            case (.local, .local):
+                throw ContainerizationError(
+                    .invalidArgument,
+                    message: "one of source or destination must be a container reference (container_id:path)")
+            }
+        }
+    }
+}

Sources/Helpers/APIServer/APIServer+Start.swift

@@ -247,6 +247,8 @@ extension APIServer {
             routes[XPCRoute.containerKill] = harness.kill
             routes[XPCRoute.containerStats] = harness.stats
             routes[XPCRoute.containerDiskUsage] = harness.diskUsage
+            routes[XPCRoute.containerCopyIn] = harness.copyIn
+            routes[XPCRoute.containerCopyOut] = harness.copyOut
             routes[XPCRoute.containerExport] = harness.export
 
             return service

Sources/Helpers/RuntimeLinux/RuntimeLinuxHelper+Start.swift

@@ -100,6 +100,8 @@ extension RuntimeLinuxHelper {
                         SandboxRoutes.dial.rawValue: server.dial,
                         SandboxRoutes.shutdown.rawValue: server.shutdown,
                         SandboxRoutes.statistics.rawValue: server.statistics,
+                        SandboxRoutes.copyIn.rawValue: server.copyIn,
+                        SandboxRoutes.copyOut.rawValue: server.copyOut,
                     ],
                     log: log
                 )

Sources/Services/ContainerAPIService/Client/ContainerClient.swift

@@ -299,6 +299,43 @@ public struct ContainerClient: Sendable {
         return fh
     }
 
+    /// Copy a file from the host into the container.
+    public func copyIn(id: String, source: URL, destination: URL, mode: UInt32 = 0o644) async throws {
+        let request = XPCMessage(route: .containerCopyIn)
+        request.set(key: .id, value: id)
+        request.set(key: .sourcePath, value: source.path)
+        request.set(key: .destinationPath, value: destination.path)
+        request.set(key: .fileMode, value: UInt64(mode))
+
+        do {
+            try await xpcSend(message: request, timeout: .seconds(300))
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to copy into container \(id)",
+                cause: error
+            )
+        }
+    }
+
+    /// Copy a file from the container to the host.
+    public func copyOut(id: String, source: URL, destination: URL) async throws {
+        let request = XPCMessage(route: .containerCopyOut)
+        request.set(key: .id, value: id)
+        request.set(key: .sourcePath, value: source.path)
+        request.set(key: .destinationPath, value: destination.path)
+
+        do {
+            try await xpcSend(message: request, timeout: .seconds(300))
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to copy from container \(id)",
+                cause: error
+            )
+        }
+    }
+
     /// Get resource usage statistics for a container.
     public func stats(id: String) async throws -> ContainerStats {
         let request = XPCMessage(route: .containerStats)

Sources/Services/ContainerAPIService/Client/XPC+.swift

@@ -123,14 +123,19 @@ public enum XPCKeys: String {
     case volumeContainerId
 
     /// Container statistics
-    case statistics
+    case statisticshttps://github.com/apple/container/pull/1190/conflict?name=Sources%252FHelpers%252FAPIServer%252FAPIServer%252BStart.swift&ancestor_oid=53175b91c6a1d7019854596f41660d0e45600ba0&base_oid=155d6c3448d8a05053ad3494b8ab58ef619757b2&head_oid=f5de594190fdf80b039e02950c732a203ddaeca0
     case containerSize
 
     /// Container list filters
     case listFilters
 
     /// Disk usage
     case diskUsageStats
+
+    /// Copy parameters
+    case sourcePath
+    case destinationPath
+    case fileMode
 }
 
 public enum XPCRoute: String {
@@ -150,6 +155,8 @@ public enum XPCRoute: String {
     case containerEvent
     case containerStats
     case containerDiskUsage
+    case containerCopyIn
+    case containerCopyOut
     case containerExport
 
     case pluginLoad

Sources/Services/ContainerAPIService/Server/Containers/ContainersHarness.swift

@@ -290,6 +290,57 @@ public struct ContainersHarness: Sendable {
         return reply
     }
 
+    @Sendable
+    public func copyIn(_ message: XPCMessage) async throws -> XPCMessage {
+        guard let id = message.string(key: .id) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "id cannot be empty"
+            )
+        }
+        guard let sourcePath = message.string(key: .sourcePath) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "source path cannot be empty"
+            )
+        }
+        guard let destinationPath = message.string(key: .destinationPath) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "destination path cannot be empty"
+            )
+        }
+        let mode = UInt32(message.uint64(key: .fileMode))
+
+        try await service.copyIn(id: id, source: sourcePath, destination: destinationPath, mode: mode)
+        return message.reply()
+    }
+
+    @Sendable
+    public func copyOut(_ message: XPCMessage) async throws -> XPCMessage {
+        guard let id = message.string(key: .id) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "id cannot be empty"
+            )
+        }
+        guard let sourcePath = message.string(key: .sourcePath) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "source path cannot be empty"
+            )
+        }
+        guard let destinationPath = message.string(key: .destinationPath) else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "destination path cannot be empty"
+            )
+        }
+
+        try await service.copyOut(id: id, source: sourcePath, destination: destinationPath)
+        return message.reply()
+    }
+
     @Sendable
     public func stats(_ message: XPCMessage) async throws -> XPCMessage {
         let id = message.string(key: .id)

Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift

@@ -749,6 +749,30 @@ public actor ContainersService {
         }
     }
 
+    /// Copy a file from the host into the container.
+    public func copyIn(id: String, source: String, destination: String, mode: UInt32) async throws {
+        self.log.debug("\(#function)")
+
+        let state = try self._getContainerState(id: id)
+        guard state.snapshot.status == .running else {
+            throw ContainerizationError(.invalidState, message: "container \(id) is not running")
+        }
+        let client = try state.getClient()
+        try await client.copyIn(source: source, destination: destination, mode: mode)
+    }
+
+    /// Copy a file from the container to the host.
+    public func copyOut(id: String, source: String, destination: String) async throws {
+        self.log.debug("\(#function)")
+
+        let state = try self._getContainerState(id: id)
+        guard state.snapshot.status == .running else {
+            throw ContainerizationError(.invalidState, message: "container \(id) is not running")
+        }
+        let client = try state.getClient()
+        try await client.copyOut(source: source, destination: destination)
+    }
+
     /// Get statistics for the container.
     public func stats(id: String) async throws -> ContainerStats {
         log.debug(

Sources/Services/ContainerSandboxService/Client/SandboxClient.swift

@@ -277,6 +277,39 @@ extension SandboxClient {
         }
     }
 
+    public func copyIn(source: String, destination: String, mode: UInt32) async throws {
+        let request = XPCMessage(route: SandboxRoutes.copyIn.rawValue)
+        request.set(key: SandboxKeys.sourcePath.rawValue, value: source)
+        request.set(key: SandboxKeys.destinationPath.rawValue, value: destination)
+        request.set(key: SandboxKeys.fileMode.rawValue, value: UInt64(mode))
+
+        do {
+            try await self.client.send(request, responseTimeout: .seconds(300))
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to copy into container \(self.id)",
+                cause: error
+            )
+        }
+    }
+
+    public func copyOut(source: String, destination: String) async throws {
+        let request = XPCMessage(route: SandboxRoutes.copyOut.rawValue)
+        request.set(key: SandboxKeys.sourcePath.rawValue, value: source)
+        request.set(key: SandboxKeys.destinationPath.rawValue, value: destination)
+
+        do {
+            try await self.client.send(request, responseTimeout: .seconds(300))
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to copy from container \(self.id)",
+                cause: error
+            )
+        }
+    }
+
     public func statistics() async throws -> ContainerStats {
         let request = XPCMessage(route: SandboxRoutes.statistics.rawValue)
 

Sources/Services/ContainerSandboxService/Client/SandboxKeys.swift

@@ -43,6 +43,10 @@ public enum SandboxKeys: String {
     /// Container statistics
     case statistics
 
+    /// Copy parameters
+    case sourcePath
+    case destinationPath
+    case fileMode
     /// Network resource keys.
     case allocatedAttachments
     case networkAdditionalData

Sources/Services/ContainerSandboxService/Client/SandboxRoutes.swift

@@ -41,4 +41,8 @@ public enum SandboxRoutes: String {
     case shutdown = "com.apple.container.sandbox/shutdown"
     /// Get statistics for the sandbox.
     case statistics = "com.apple.container.sandbox/statistics"
+    /// Copy a file into the container.
+    case copyIn = "com.apple.container.sandbox/copyIn"
+    /// Copy a file out of the container.
+    case copyOut = "com.apple.container.sandbox/copyOut"
 }