From SSH, graphical access, and file transfers to Xcode, Runners, fastlane, and node networking, use reproducible commands to narrow the scope before changing configuration or opening a ticket.
$ ssh -v "$MAC_USER@$MAC_HOST"
debug1: Authentication succeeded
$ xcodebuild -version
Xcode toolchain ready
$ scutil --dns | grep nameserver
Resolver path verified
Open the relevant instance in the console and confirm its host address, login username, and initial credentials. The first connection has three goals: verify the target host, access the system, and switch subsequent logins to key-based authentication.
First confirm that the instance is running normally, then write the host address and username shown in the console to separate local environment variables. Never put passwords, private keys, or complete credentials in repositories, chat records, or automation logs.
export MAC_HOST="host address shown in console"
export MAC_USER="username shown in console"
test -n "$MAC_HOST" && test -n "$MAC_USER" && echo "connection variables ready"After connecting, compare the fingerprint shown in the terminal with the console information. If the host address changed, the fingerprint changed after a reinstall, or your machine has an old record, do not simply ignore the warning. First confirm that the instance is still the same device.
ssh -v "$MAC_USER@$MAC_HOST"
ssh-keygen -F "$MAC_HOST"Generate a separate Ed25519 key for the Cloud Mac to simplify rotation and revocation. After installing the public key, keep the current session open and use a second terminal to verify key-based login before closing the original session.
ssh-keygen -t ed25519 -a 64 -f "$HOME/.ssh/macrents_build"
cat "$HOME/.ssh/macrents_build.pub" | ssh "$MAC_USER@$MAC_HOST" 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'
ssh -i "$HOME/.ssh/macrents_build" "$MAC_USER@$MAC_HOST"Set a dedicated alias, key path, and keepalive parameters for this instance. Once connected, record the macOS version, available disk space, current user, and system time so you can quickly detect environmental changes when builds fail.
sw_vers
whoami
date
df -h /
uptimeFor timeouts, check the local network, port, node route, and source-address restrictions first. If you see Permission denied check the username, key file, file permissions, and server-side authorization records. Do not repeatedly change DNS during authentication failures or keep resetting credentials when the network is unreachable.
Use SSH first for builds and automation. Use graphical remote desktop access for UI debugging, simulators, or desktop tools. For bulk project and artifact synchronization, use resumable file transfer.
Ideal for pulling repositories, installing dependencies, running builds, and managing long-running tasks. When the connection is unstable, enable client keepalives and use verbose logs to determine whether the interruption occurred during the handshake, authentication, or session.
ssh -vvv -o ServerAliveInterval=30 -o ServerAliveCountMax=4 "$MAC_USER@$MAC_HOST"Open the graphical access entry point from the console for Xcode UI debugging, simulator observation, and tools that require desktop interaction. If the session stutters, lower the display resolution and refresh rate first, then compare terminal latency to distinguish encoding issues from network-path problems.
For a small number of files, use scp. For large directories and build caches, use rsync. Exclude derived data, temporary archives, and dependency caches before transferring to avoid repeatedly sending rebuildable content across borders.
rsync -azP --partial --exclude DerivedData/ ./project/ "$MAC_USER@$MAC_HOST:~/workspace/project/"Do not rely on a single foreground terminal for long builds. Use a session manager or macOS service mechanism to keep tasks running, and regularly write logs to a controlled directory. Revoke public keys and access tokens when they are no longer needed.
tmux new -s build
tmux attach -t build
tail -n 200 "$HOME/logs/build.log"The Xcode shown in the GUI may differ from the developer directory selected by the command line. Record the path, version, SDK, simulator, and signing environment before rerunning a minimal build command.
xcode-select -p
xcodebuild -version
xcodebuild -showsdks
xcrun simctl list devices available
xcrun --find swift
swift --version
security list-keychains -d user
security find-identity -v -p codesigningxcode-select -p should point to the Xcode required for this build. If the path is wrong, stop the Runner first, switch the directory, and restart it so running tasks do not inherit the old environment.
If the target SDK does not appear in the -showsdks output, changing project parameters will not add the missing toolchain. For simulator tasks, also verify device status, runtime version, and available disk space.
The presence of a signing identity does not mean an automation process can read its private key. Compare the user, keychain search list, and unlock state of the interactive terminal with those of the Runner service.
Pin the workspace, scheme, configuration, and destination first, then disable unrelated scripts. Keep the complete exit code and trailing log context; do not capture only the final error line.
set -o pipefail
xcodebuild -workspace Project.xcworkspace -scheme Project -configuration Release -destination 'generic/platform=macOS' clean build | tee "$HOME/logs/xcode-build.log"
printf 'exit_code=%s\n' "$?"Self-hosted Runners and persistent agents should pin the runtime user, working directory, toolchain path, cache boundaries, and key-access method. Stabilize one minimal task first, then gradually restore concurrency, caching, and distribution steps.
Generate one-time registration details in the project or organization settings, then register the Runner on the Cloud Mac under a dedicated system user. Labels should distinguish at least the operating system, chip tier, and purpose; route macOS jobs only to matching nodes.
whoami
xcode-select -p
printenv | sort
df -h "$HOME"Choose an execution method suited to macOS during registration and restrict job sources with protected tags. The service user must access the project directory and required keychains, but should not receive unrelated system privileges.
git status --short
git rev-parse HEAD
shasum -a 256 "$HOME/artifacts/app.zip"
du -sh "$HOME/build-cache"Manage an in-house or other build agent with the macOS service mechanism, explicitly defining the startup user, environment-variable file, standard output, and restart policy. Do not rely on a remote desktop session staying connected.
launchctl list | grep build
ps aux | grep '[b]uild-agent'
lsof -nP -iTCP -sTCP:ESTABLISHED
tail -n 200 "$HOME/logs/agent.log"Do not reinstall every dependency immediately. First identify whether the failure occurred during signing preparation, archiving, exporting, or uploading, then collect inputs, exit codes, and redacted logs for that stage.
| Diagnostic layer | Common symptom | Check first | Response principle |
|---|---|---|---|
| Certificates | Signing identity not found or identity count is zero | security find-identity -v -p codesigning | Confirm the target keychain, certificate validity, and private-key pairing |
| Provisioning profiles | Identifier mismatch or inconsistent capabilities | Target identifier, team information, required capabilities, and file contents | Do not mix provisioning profiles from different projects or environments |
| Keychain permissions | Build works in the terminal but the Runner cannot sign | Runtime user, search list, unlock state, and private-key access controls | Allow the automation process to access only the signing materials required for this job |
| Environment variables | Interactive execution succeeds but the service lacks parameters | printenv redacted differences and service startup configuration | Inject variables explicitly instead of relying on interactive shell startup files |
| Upload logs | Archive succeeds but upload stops or returns a nonzero status | Complete exit code, retry count, file size, and network timeline | Verify the artifact first, then separate upload issues from build issues |
The most common cause is a different runtime user, or a service process that did not inherit the interactive session's keychain search list. Record whoami,security list-keychains -d user and the signing-identity output separately, then compare the two execution environments. Do not hide user-boundary problems by loosening access to every private key.
With the same commit, Xcode path, and working directory, output redacted variable-name lists from the interactive terminal and the Runner separately. Compare only whether variables exist; never print token values. If the variables are complete, check the working directory, shell type, dependency versions, and execution user.
Keep the lane name, failure stage, complete exit code, Xcode and fastlane versions, job start and end times, trailing context, and reproducible commands. Remove access tokens, certificate passwords, private keys, session information, and personal data before submitting. A screenshot showing only the final error line is usually not enough to diagnose the issue.
Choose a node based on your team's location, code and dependency sources, artifact destinations, and actual network paths. Do not rely on a single latency result; compare round-trip latency, packet loss, DNS resolution, and route changes, and record the testing window.
Suitable for teams and dependency paths serving Southeast Asia. If latency suddenly increases, compare office, mobile, and another egress network to determine whether the local carrier path changed.
Suitable for projects in Japan and Northeast Asia. When troubleshooting cross-border connectivity, record direct latency, hop count, and file-transfer speed rather than judging only by the apparent smoothness of the graphical desktop.
Suitable for access from South Korea and nearby regions. If SSH works but large-file speeds are unstable, check packet loss, path MTU, local proxies, and the number of concurrent transfers.
Suitable for cross-border collaboration across Asia and distributed teams. If one network reaches the node while another times out, save both route results and identify each source network type.
Use short tests to confirm reachability and sustained tests to detect jitter and intermittent packet loss. Set $MAC_HOST to the current instance address, then run:
ping -c 20 "$MAC_HOST"
nc -vz -w 5 "$MAC_HOST" 22
traceroute "$MAC_HOST"When connecting by hostname, first confirm that resolution is stable. If connecting directly by address also fails, the problem is usually not DNS. Record the current local resolver and query results:
scutil --dns
dscacheutil -q host -a name "$MAC_HOST"
dig "$MAC_HOST"Confirm that traffic leaves through the expected interface, and check whether a local VPN, proxy, or multiple network interfaces changed the default route. Restore the original network settings after testing, and do not change multiple variables at once:
route -n get "$MAC_HOST"
netstat -rn
ifconfig
networkQualityWhen the SSH handshake is normal but transfers are slow, repeat the test with a fixed file and record its size, duration, and client network. Do not directly compare results from different project directories or compression settings:
time scp "$HOME/test-transfer.bin" "$MAC_USER@$MAC_HOST:~/"
shasum -a 256 "$HOME/test-transfer.bin"
ssh "$MAC_USER@$MAC_HOST" 'shasum -a 256 ~/test-transfer.bin'When connectivity is abnormal, collect evidence by source network, target node, protocol, and time window. A single speed test does not represent long-term path quality; run the same test at least once on the affected network and once on a comparison network to determine whether the issue is local egress, the cross-border path, or the target connection layer.
Existing users should sign in to the console first to open a ticket, allowing the order and instance to be linked. If you cannot access the console, email support@macrents.com. Both methods enter the same support workflow.
Host addresses may retain the necessary portion in logs, but remove tokens, passwords, request headers, signing materials, and personal data. If support needs more information, the team will specify the minimum required scope in the ticket.
For connection interruptions, inaccessible instances, or persistently failing builds, specify the business impact. For pre-sales configuration questions, email us directly. For technical issues involving existing orders, host status, or logs, use a console ticket first.
All three tiers include a dedicated physical Mac mini node, not a virtual machine. Choose based on build concurrency, unified memory requirements, and rental term. If you already have an instance, sign in to the console to open a ticket.