Xcode Cloud Builds & Remote Mac Access

Four handoff steps to your Mac credentials

Allow about 1 minute each for signup, setup, payment, and provisioning—around 4 minutes in total when everything goes smoothly. This is an estimate for setup, not a guaranteed delivery time. Check the console for the latest status of email delivery, payment confirmation, and provisioning.

Sign up and open the console
About 1 minute
Use a team email address that can receive verification codes. Follow the prompts to sign up and set a password. Use an inbox managed by an active team member so you can check orders, renewals, and support tickets later. Never forward verification codes to public build logs.
Choose a Mac, billing period, and region
About 1 minute
Choose Push M4 S or Push M4 L, then select a billing period and region. For everyday CI on a single app, consider the 16 GB plan; for archiving multiple targets in parallel, consider 24 GB. Check the console for real-time availability.
Pay in USD
About 1 minute
Choose USDT-TRC20, or pay with Visa, Mastercard, or Amex via Stripe. Available payment gateways are shown at checkout. For on-chain transfers, verify the network, address, and amount, then wait for confirmation in the console; initiating a payment does not mean your Mac is ready.
Get your Mac and connection details
About 1 minute
Once your Mac is provisioned, check the region, connection address, port, and login user in your order or instance details, then retrieve your SSH/VNC credentials. Keep your order number handy for support tickets; never share your login password or private key.

Keep interaction close to your team and builds close to their dependencies

All five regions offer two dedicated Mac plans. Start by narrowing your options based on where the people who operate the build machine are located, then check the routes between your repository, dependency sources, and artifact storage. A convenient time zone doesn’t guarantee low latency; test VNC responsiveness and dependency downloads separately.

Singapore

A good first option for teams mainly based in Southeast Asia. Test your usual remote connection and dependency downloads together.

Team time zone: UTC+8

Tokyo

A good first option for teams working mainly on Japan business hours. Use fixed runner labels to keep jobs on the right region.

Team time zone: UTC+9

Seoul

Worth considering if team members in Korea frequently use the desktop. Test responsiveness over your actual office network.

Team time zone: UTC+9

Hong Kong

Consider it for routes serving southern China and Southeast Asia. Use remote desktop for interactive work and SSH for command-line tasks; keep logs in your build system.

Team time zone: UTC+8

US East

A good option when your team needs interactive access during North American business hours. Use UTC for cross-region handoffs and task timestamps.

Team time zone: UTC−5 / UTC−4

US East observes daylight saving time. If teams in both regions need frequent access, consider renting a nearby Mac in each region and coordinating jobs through a CI queue. For multiple heavy jobs on one Mac, set a concurrency limit.

Connect over SSH, then open the macOS desktop

Get the connection address, port, and user from the console; don’t reuse credentials from another order. The commands below prompt you for the actual values. Before running them, make sure your local machine has an SSH client.

SSH: Verify command-line access

Run this in your local terminal. On first connection, verify the host fingerprint. If the console doesn’t provide a way to verify it, confirm through a support ticket rather than skipping host identity checks.

printf 'Connection address: '
read -r MAC_HOST
printf 'SSH port: '
read -r MAC_PORT
printf 'Login user: '
read -r MAC_USER
ssh -p "$MAC_PORT" "$MAC_USER@$MAC_HOST"

After logging in, run whoami and sw_vers to verify the user and system details. When setting up SSH keys, upload only the public key; keep the private key on your device or in your CI secrets manager.

VNC: Check desktop access

Sign in to the console and open the connection details for your provisioned instance.
Connect to the remote desktop using the method listed for your instance, and verify the address and authentication details.
Once in macOS, check the keyboard, display, and network. Set a VNC password according to your team’s policy.
Complete the initial Xcode prompts and grant any required Keychain permissions, then return to SSH to run the build.

Use the desktop for GUI authorization and the command line for reproducible scripts. If a connection times out, check the port, instance status, and local network before opening a support ticket. Repeatedly changing the password won’t diagnose a network issue.

Create a reproducible archive receipt

Your first build has four checks: toolchain, project, signing, and export. These commands are for iOS projects that use a workspace. For a project-only setup, replace -workspace with -project and use your project’s filename.

Verify the active toolchain

Check which Xcode is actually selected by the system—not just what’s installed in the Applications folder. If multiple versions are installed, switch to the app path specified by your project, then verify the version and SDK again.

xcode-select -p
xcodebuild -version
xcodebuild -showsdks
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Clone the repository and find the shared scheme

Enter a repository URL you can read. Authenticate with an SSH key or a secure credentials manager; don’t include access tokens in the command. Run your project’s dependency setup first, then list its workspaces and schemes.

printf 'Repository URL: '
read -r REPOSITORY_URL
git clone "$REPOSITORY_URL" app
cd app
git rev-parse HEAD
find . -name '*.xcworkspace' -prune
xcodebuild -list -workspace MyApp.xcworkspace

Use a fixed directory to run the archive

Replace MyApp.xcworkspace and MyApp with the actual names you confirmed in the previous step. For builds that require device signing, securely import the matching certificate and provisioning profile, and make sure the build process can access the Keychain.

mkdir -p build
xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -derivedDataPath build/DerivedData \
  -archivePath build/MyApp.xcarchive \
  archive

Export a deliverable using your project’s settings

ExportOptions.plist Use the signing and distribution settings defined by your project; don’t copy them from another team. A successful archive doesn’t guarantee a successful export. Keep the exit status and logs for both steps.

xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions.plist

test -d build/MyApp.xcarchive
find build/export -maxdepth 1 -type f -print

Record four handoff details—never keys

Record the commit SHA, Xcode version, actual scheme, and artifact path. If the first build fails, check the first error: for dependency resolution, check the network and lockfile; for signing, check the certificate and provisioning profile; for export, check the export settings. Don’t change the region, toolchain, and signing settings all at once when retrying.

Hand your verified command over to CI

First, get the build working manually under the same build user, then register a self-hosted runner. Always-on hosting keeps the machine available, but your team still needs to configure and check runner startup, certificate validity, and CI queue delays.

Register a runner and label where jobs should go

Get the macOS ARM64 runner setup instructions from your CI platform’s project or organization settings. Use registration details for the current project, not an expired token. Choose labels that identify the region, architecture, and purpose.

GitHub Actions: Generate a registration command under Self-hosted runners and check its repository access scope.
GitLab Runner: Register it with the URL and token provided by your project, then choose an executor suitable for Xcode jobs.
Allow only trusted pipelines to access signing assets. Don’t run unreviewed code directly on a Mac that holds secrets.

Start with one build job when you first connect CI. Monitor memory, disk space, and build times before increasing concurrency. A dedicated Mac doesn’t mean every archive should run at once.

Enable startup and check the background service

After extracting and registering a GitHub Actions runner, you can use the service script included in its installation directory. These are not download or registration commands; first complete the previous step using the CI platform’s instructions.

./svc.sh install
./svc.sh start
./svc.sh status

Check that the service script reports the runner as running and that the CI platform shows it online. A LaunchAgent typically depends on that user’s login session. For unattended startup, configure and verify it using the runner’s supported approach; installing a service alone doesn’t guarantee builds will work after a restart.

Final check: build an artifact after closing the terminal

Close the terminal where you started the runner manually, then trigger a controlled job from CI. Verify the run user, selected Xcode, Keychain access, cache directory, and artifact upload. For a node intended to run unattended, also check the runner after recovery. Before restarting, make sure no other jobs are running.

Keep DerivedData and dependency caches on your dedicated Mac. Cache keys should distinguish at least the toolchain, dependency lockfile, and build configuration. Set cleanup rules before retaining artifacts so caches don’t fill the system disk.

Reuse this receipt for your next code push

Once the connection and first artifact are verified, record the region, toolchain, and build command for your team. For details on version switching and caching, read the guide; to add build capacity, review the plans first.

Read the operations guide Choose a dedicated Mac plan