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
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
import CuaSDK
import CuaSpaces
import Foundation
// MARK: - The image list
/// One entry of `libs/images/sandbox-images.json`.
///
/// The list itself is generated (`SandboxImages.generated.swift`, from
/// `scripts/gen-images.mjs`), so the picker offers exactly what the docs and
/// the other apps offer.
struct SandboxImage: Identifiable, Hashable {
var ref: String
var group: String
/// `linux`, `windows` or `macos`.
var os: String
var name: String
/// `container` or `vm`.
var variant: String
var summary: String
/// Whether the image runs cua-spacesd. Without it a Space has no
/// capabilities beyond its declared services.
var spacesd: Bool
/// How the image runs locally (`container`, `qemu`, `lume`), `nil` when
/// it cannot run on this machine.
var local: String?
/// The cloud engine (`gvisor`, `kubevirt`), `nil` when the image has no
/// cloud variant.
var cloud: String?
/// `slim`, `full` (the default) or `xcode`; `nil` outside the
/// canonical images.
var tier: String? = nil
var id: String { ref }
func supports(_ placement: SpacePlacement) -> Bool {
switch placement {
case .cloud: return cloud != nil
case .local: return local != nil
}
}
/// What kind of machine the image is (`variant` in the catalog).
var kind: SpaceKind { variant == "vm" ? .vm : .container }
/// The engines this image can run on in `placement`, `auto` first. Only
/// what the catalog says the image runs, so the wizard never offers a
/// combination the image cannot run. Empty when it cannot run there.
func runtimes(on placement: SpacePlacement) -> [SpaceRuntime] {
switch placement {
case .local:
switch local {
case "container": return SpaceRuntime.offered(on: .local, kind: .container)
case "qemu": return [.auto, .qemu]
case "lume": return [.auto, .lume]
default: return []
}
case .cloud:
guard let engine = cloud.flatMap(SpaceRuntime.init(rawValue:)) else { return [] }
return [.auto, engine]
}
}
}
struct SandboxImageGroup: Identifiable, Hashable {
var id: String
var label: String
}
enum SandboxImages {
/// The published images of one operating system, in file order.
static func images(for os: SandboxOS) -> [SandboxImage] {
published.filter { $0.os == os.rawValue }
}
static func image(_ ref: String) -> SandboxImage? {
published.first { $0.ref == ref }
}
/// What the picker shows: each group label with its images, in file order.
/// `os` narrows it to one system; `nil` is every published image.
static func pickerSections(for os: SandboxOS? = nil) -> [(group: SandboxImageGroup, images: [SandboxImage])] {
groups.compactMap { g in
let rows = published.filter { $0.group == g.id && (os == nil || $0.os == os!.rawValue) }
return rows.isEmpty ? nil : (g, rows)
}
}
}
enum SandboxOS: String, CaseIterable, Identifiable {
case linux, windows, macos
var id: String { rawValue }
var label: String {
switch self {
case .linux: return "Linux"
case .windows: return "Windows"
case .macos: return "macOS"
}
}
var symbol: String {
switch self {
case .linux: return "terminal"
case .windows: return "pc"
case .macos: return "macwindow"
}
}
/// An OS tile is only offered when at least one published image runs it.
var isAvailable: Bool { !SandboxImages.images(for: self).isEmpty }
}
/// Where a Space runs: the SDK's `on`.
enum SpacePlacement: String, CaseIterable, Identifiable {
case local, cloud
var id: String { rawValue }
var label: String { self == .cloud ? "Cua Cloud" : "This machine" }
var location: SpaceLocation { self == .cloud ? .cloud : .local }
/// The user's default location (`cua config set default.on`,
/// `CUA_DEFAULT_ON`, else `local`), which the wizard starts from.
static var configuredDefault: SpacePlacement {
(try? CuaSDK.configGet(key: "default.on").value) == "cloud" ? .cloud : .local
}
}
// MARK: - The plan
/// Everything the New Space wizard collects, and the one SDK call it maps to.
struct SpacePlan: Equatable {
var os: SandboxOS = .linux
var imageRef: String = SandboxImages.images(for: .linux).first?.ref ?? ""
var placement: SpacePlacement = .local
/// `auto` unless the advanced chooser picked an engine.
var runtime: SpaceRuntime = .auto
var cpus: Int = SpacePlan.defaultCPUs
var memoryGB: Int = SpacePlan.defaultMemoryGB
var name: String = ""
var openWhenReady: Bool = true
static let defaultCPUs = 2
static let defaultMemoryGB = 4
static let cpuRange = 1...max(2, ProcessInfo.processInfo.activeProcessorCount)
static let memoryRange = 2...max(4, Int(ProcessInfo.processInfo.physicalMemory >> 30) / 2)
var image: SandboxImage? { SandboxImages.image(imageRef) }
/// Pick an OS: the image follows (first of that OS), and the placement
/// moves to one the image supports.
mutating func select(os: SandboxOS) {
self.os = os
if image?.os != os.rawValue, let first = SandboxImages.images(for: os).first {
select(image: first.ref)
}
}
mutating func select(image ref: String) {
imageRef = ref
guard let image else { return }
os = SandboxOS(rawValue: image.os) ?? os
if !image.supports(placement) {
placement = image.supports(.cloud) ? .cloud : .local
}
keepRuntimeValid()
}
mutating func select(placement: SpacePlacement) {
guard image?.supports(placement) ?? false else { return }
self.placement = placement
keepRuntimeValid()
}
/// The engines the advanced chooser offers: what this image runs where
/// the plan says, `auto` first.
var runtimeOptions: [SpaceRuntime] { image?.runtimes(on: placement) ?? [] }
mutating func select(runtime: SpaceRuntime) {
guard runtimeOptions.contains(runtime) else { return }
self.runtime = runtime
}
private mutating func keepRuntimeValid() {
if !runtimeOptions.contains(runtime) { runtime = .auto }
}
// MARK: Validation
/// A Space name is a DNS label: 1 to 63 of `a-z`, `0-9` and `-`, not
/// starting or ending with `-`.
static func isDNSLabel(_ s: String) -> Bool {
guard (1...63).contains(s.count), s.first != "-", s.last != "-" else { return false }
return s.unicodeScalars.allSatisfy {
("a"..."z").contains($0) || ("0"..."9").contains($0) || $0 == "-"
}
}
/// Lowercase, spaces to hyphens, everything else dropped.
static func suggestedName(from s: String) -> String {
var out = ""
for ch in s.lowercased() {
if ch.isASCII, ch.isLetter || ch.isNumber { out.append(ch) }
else if ch == " " || ch == "-" || ch == "_" || ch == "." {
if !out.isEmpty, out.last != "-" { out.append("-") }
}
}
while out.last == "-" { out.removeLast() }
return String(out.prefix(63))
}
var nameError: String? {
if name.isEmpty { return "Give the Space a name." }
return Self.isDNSLabel(name)
? nil
: "Use lowercase letters, digits and hyphens (a DNS label, at most 63 characters)."
}
var systemError: String? {
guard let image else { return "Choose an image." }
if image.os != os.rawValue { return "\(image.name) is not a \(os.label) image." }
if !image.supports(placement) {
return placement == .cloud
? "\(image.name) has no Cua Cloud variant. Run it on this machine."
: "\(image.name) cannot run on this machine. Run it in Cua Cloud."
}
if !runtimeOptions.contains(runtime) {
return "\(image.name) does not run on \(runtime.rawValue) in \(placement.label)."
}
return nil
}
var isValid: Bool { systemError == nil && nameError == nil }
/// Shown on the Options step when the image has no cua-spacesd.
var spacesdWarning: String? {
guard let image, !image.spacesd else { return nil }
return "\(image.name) does not run cua-spacesd yet, so the Space starts with no "
+ "capabilities: no screen, shell or files. Bots cannot work in it."
}
/// The call `Create` makes. The image reference goes as is: the SDK
/// reads the image's manifest to pick the variant and, with `auto`, the
/// engine. CPUs and memory apply to local Spaces only.
var request: SpaceCreateRequest? {
guard isValid, let image else { return nil }
return SpaceCreateRequest(
on: placement.location, kind: image.kind, runtime: runtime,
image: image.ref, name: name,
cpus: placement == .local ? cpus : nil,
memoryMB: placement == .local ? memoryGB * 1024 : nil,
spacesd: image.spacesd)
}
}
/// One Space creation, in SDK terms: `Spaces.create(options:)`
/// (`create_space`). `on: .local` is free; `on: .cloud` is metered.
struct SpaceCreateRequest: Equatable {
var on: SpaceLocation
var kind: SpaceKind
var runtime: SpaceRuntime
var image: String
var name: String
var cpus: Int?
var memoryMB: Int?
var spacesd: Bool
}
/// `Create`, minus the UI: validate the plan, then make exactly one SDK call.
enum SpaceCreationFlow {
static func create(_ plan: SpacePlan, with creator: SpaceCreating) async throws -> String {
guard let request = plan.request else {
throw SpaceCreationError.invalidPlan(plan.systemError ?? plan.nameError ?? "invalid plan")
}
return try await creator.createSpace(request)
}
}
/// The part of a Spaces client that can create a Space. Separate from
/// `SpacesClient` so the app's everyday path cannot create one by accident.
protocol SpaceCreating: AnyObject {
/// Create the Space and return its id once the SDK reports it.
func createSpace(_ request: SpaceCreateRequest) async throws -> String
}
enum SpaceCreationError: Error, CustomStringConvertible {
case invalidPlan(String)
case noSpacesRuntime
case noSpaceID
var description: String {
switch self {
case .invalidPlan(let why): return why
case .noSpacesRuntime:
return "Creating a Space needs the cua SDK. The app is offline (demo client)."
case .noSpaceID: return "The SDK did not return a Space id."
}
}
}