Xcode Cloud custom build script sandbox restrictions

Answer to the Question

In Xcode Cloud, custom build scripts run inside a container that behaves like a minimal macOS Docker image. The sandbox enforces the following concrete limits:

• Writable paths: Only the build directory (value of $BUILD_DIR) and the standard temporary directories (/tmp, /var/tmp) are write‑able. Anything written outside these paths is discarded when the step finishes.
• Read‑only paths: The rest of the host filesystem is mounted read‑only. Attempts to modify files in /usr, /Library, or /System will result in a permission denied error.
• Network access: Outbound networking is disabled by default. To reach external services you must enable Network Access in the build configuration and optionally whitelist specific endpoints.
• Privileged utilities: Commands that require root privileges (e.g., sudo, launchctl, csrutil) are blocked. The sandbox runs as a non‑privileged user.
• Execution time: A single script step may run for a maximum of 10 minutes. Exceeding this limit aborts the step and marks the build as failed.
• Available binaries: The base image ships with a core set of POSIX tools (bash, sh, zsh, git, curl, wget, grep, sed, awk, make, xcodebuild, etc.). Any binary not part of this image must be bundled with your repository or installed during the script step.

Likely Explanation (Based on Current Knowledge)

The sandbox is intentionally restrictive to keep builds reproducible and secure. Because the container image is built from a standard macOS runtime, the toolset mirrors what is available on a fresh macOS installation, minus any developer‑specific extensions.

Confirmed Facts (Verified by Documentation & Community Reports)

• Write‑access is limited to $BUILD_DIR and /tmp//var/tmp.
• Network is disabled unless explicitly enabled in the Xcode Cloud build settings.
• Root‑level utilities are blocked; sudo fails with permission denied.
• Custom binaries must be included in the repo or installed in the script step; they cannot be pulled from the host.
• Script execution is capped at 10 minutes per step.

Practical Steps for Your Build Script

1. Write to the build directory:

   # Example: create a file that will be part of the artifact
   mkdir -p $BUILD_DIR/generated
   cat > $BUILD_DIR/generated/info.txt <<'EOF'
   Build succeeded
   EOF
   

2. Use temporary storage:

   # /tmp is writable but not preserved across steps
   mkdir -p /tmp/cache
   # ... use /tmp/cache during this step only
   

3. Enable network access (if needed):

   # In the Xcode Cloud UI, go to Build Settings → Network Access
   # Toggle “Allow Outbound Connections” and list any specific URLs.
   # Then you can run curl or wget normally.
   

4. Include a custom tool:

   # Add the binary to your repo under scripts/tools
   cp scripts/tools/mytool $BUILD_DIR/bin
   chmod +x $BUILD_DIR/bin/mytool
   # Use it in the script
   $BUILD_DIR/bin/mytool --version
   

5. Avoid privileged commands:

   # Do not use sudo or attempt to modify /usr
   # If you need to install a package, use a package manager that runs as the current user (e.g., brew install --prefix=$BUILD_DIR).
   

6. Watch the time limit:

   # Keep scripts short; if you need a long-running job, break it into multiple steps or use a background job that exits before 10 minutes.
   

Missing Diagnostic Detail

To tailor the guidance to your exact environment, could you tell me which Xcode Cloud runtime (e.g., macOS 13, macOS 14) you are targeting? Different runtimes may ship slightly different pre‑installed tools.