[Build] Disable rosetta during builds with a UserDefault

Sources/CLI/Builder/BuilderStart.swift

@@ -194,7 +194,8 @@ extension Application {
                     options: []
                 ),
             ]
-            config.rosetta = true
+            // Enable Rosetta only if the user didn't ask to disable it
+            config.rosetta = ClientDefaults.getBool(key: .buildRosetta) ?? true
 
             let network = try await ClientNetwork.get(id: ClientNetwork.defaultNetworkName)
             guard case .running(_, let networkStatus) = network else {

Sources/ContainerClient/Core/ClientDefaults.swift

@@ -28,6 +28,7 @@ public enum ClientDefaults {
         case defaultInitImage = "image.init"
         case defaultKernelURL = "kernel.url"
         case defaultKernelBinaryPath = "kernel.binaryPath"
+        case buildRosetta = "build.rosetta"
     }
 
     public static func set(value: String, key: ClientDefaults.Keys) {
@@ -47,6 +48,15 @@ public enum ClientDefaults {
         udSuite.string(forKey: key.rawValue)
     }
 
+    public static func setBool(value: Bool, key: ClientDefaults.Keys) {
+        udSuite.set(value, forKey: key.rawValue)
+    }
+
+    public static func getBool(key: ClientDefaults.Keys) -> Bool? {
+        guard udSuite.object(forKey: key.rawValue) != nil else { return nil }
+        return udSuite.bool(forKey: key.rawValue)
+    }
+
     private static var udSuite: UserDefaults {
         guard let ud = UserDefaults.init(suiteName: self.userDefaultDomain) else {
             fatalError("Failed to initialize UserDefaults for domain \(self.userDefaultDomain)")
@@ -75,6 +85,9 @@ extension ClientDefaults.Keys {
                 return "vminit:latest"
             }
             return "ghcr.io/apple/containerization/vminit:\(tag)"
+        case .buildRosetta:
+            // This is a boolean key, not used with the string get() method
+            return "true"
         }
     }
 }

docs/how-to.md

@@ -235,6 +235,22 @@ Use the `--boot` option to see the logs for the virtual machine boot and init pr
 %
 </pre>
 
+## Configure container defaults
+
+`container` uses macOS user defaults to store configuration settings that persist between sessions. You can customize various aspects of container behavior, including build settings, default images, and network configuration.
+
+For a complete list of available configuration options and detailed usage instructions, see the [user defaults documentation](user-defaults.md).
+
+### Example: Disable Rosetta for builds
+
+If you want to prevent the use of Rosetta translation during container builds on Apple Silicon Macs:
+
+```bash
+defaults write com.apple.container.defaults build.rosetta -bool false
+```
+
+This is useful when you want to ensure builds only produce native arm64 images and avoid any x86_64 emulation.
+
 ## View system logs
 
 The `container system logs` command allows you to look at the log messages that `container` writes:

docs/user-defaults.md

@@ -0,0 +1,150 @@
+# User Defaults Configuration
+
+The `container` CLI uses macOS user defaults to store configuration settings. These settings persist between sessions and allow you to customize the behavior of various commands.
+
+## Viewing Current Defaults
+
+To view a specific default value, use the macOS `defaults` command:
+
+```bash
+defaults read com.apple.container.defaults <key>
+```
+
+## Available User Defaults
+
+### Build Settings
+
+#### build.rosetta
+
+Controls whether Rosetta translation is enabled during container builds. When enabled (default), allows building x86_64 images on Apple Silicon Macs.
+
+**Default:** `true`
+
+**Usage:**
+```bash
+# Disable Rosetta for builds
+defaults write com.apple.container.defaults build.rosetta -bool false
+
+# Enable Rosetta for builds (default)
+defaults write com.apple.container.defaults build.rosetta -bool true
+
+# Check current value
+defaults read com.apple.container.defaults build.rosetta
+```
+
+**Note:** Disabling Rosetta will prevent building x86_64 images on Apple Silicon Macs. This setting only affects the build process and does not impact running containers.
+
+### Image Settings
+
+#### image.builder
+
+Specifies the default BuildKit image used for building containers.
+
+**Default:** `ghcr.io/apple/container-builder-shim/builder:<version>`
+
+**Usage:**
+```bash
+# Set a custom builder image
+defaults write com.apple.container.defaults image.builder "my-registry.com/my-builder:latest"
+
+# Reset to default
+defaults delete com.apple.container.defaults image.builder
+```
+
+#### image.init
+
+Specifies the default init image used for container initialization.
+
+**Default:** `ghcr.io/apple/containerization/vminit:<version>`
+
+**Usage:**
+```bash
+# Set a custom init image
+defaults write com.apple.container.defaults image.init "my-registry.com/my-init:latest"
+```
+
+### Network Settings
+
+#### dns.domain
+
+Sets the default local DNS domain for containers.
+
+**Default:** `test`
+
+**Usage:**
+```bash
+# Set a custom DNS domain
+defaults write com.apple.container.defaults dns.domain "mycompany.local"
+
+# Alternatively, use the container CLI
+container system dns default set mycompany.local
+```
+
+### Registry Settings
+
+#### registry.domain
+
+Sets the default registry domain for pulling images.
+
+**Default:** `docker.io`
+
+**Usage:**
+```bash
+# Set a custom default registry
+defaults write com.apple.container.defaults registry.domain "ghcr.io"
+
+# Alternatively, use the container CLI
+container registry default set ghcr.io
+```
+
+### Kernel Settings
+
+#### kernel.url
+
+URL for downloading the default kernel used by containers.
+
+**Default:** `https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz`
+
+**Usage:**
+```bash
+# Set a custom kernel URL
+defaults write com.apple.container.defaults kernel.url "https://myserver.com/custom-kernel.tar.xz"
+```
+
+#### kernel.binaryPath
+
+Path within the kernel archive to the actual kernel binary.
+
+**Default:** `opt/kata/share/kata-containers/vmlinux-6.12.28-153`
+
+**Usage:**
+```bash
+# Set a custom kernel binary path
+defaults write com.apple.container.defaults kernel.binaryPath "path/to/vmlinux"
+```
+
+## Resetting Defaults
+
+To reset a specific setting to its default value:
+
+```bash
+defaults delete com.apple.container.defaults <key>
+```
+
+To reset all container defaults:
+
+```bash
+defaults delete com.apple.container.defaults
+```
+
+## Platform-Specific Settings
+
+### macOS 15 Network Configuration
+
+On macOS 15, if you experience network connectivity issues, you may need to manually configure the network subnet:
+
+```bash
+defaults write com.apple.container.defaults network.subnet 192.168.66.1/24
+```
+
+See the [technical overview](technical-overview.md#macos-15-limitations) for more details about macOS 15 limitations.