This guide brings together troubleshooting paths for connectivity, builds, runners, networking, and storage on dedicated Apple Silicon physical nodes. Each step identifies what to check, which command to run, and what result will guide your next move.
If you already have a node, first record its node ID and the time range when the issue occurred. If you have not ordered yet, review the three available configurations and four selectable nodes.
Do not change settings at multiple layers at once. Choose the category closest to the symptoms, complete its basic checks, and use the results to move to the next layer.
Start with the address, port, key permissions, host fingerprint, and credential validity. If SSH works but the graphical session does not, then check the resolution, lock state, and session recovery.
First pin the Xcode version and save the original logs. Then verify signing identities, provisioning profiles, Keychain permissions, DerivedData, and the runner working directory.
Verify the order number, rental period, node ID, and payment status in the Console. Do not submit private keys or complete payment credentials in a ticket.
Record free disk space, volume labels, network quality, and the Thunderbolt device tree. Do not format disks or rebuild volumes without a backup.
A failed connection does not necessarily mean the node is offline. First distinguish an incorrect address, unreachable port, invalid local key permissions, changed host fingerprint, or server-side authentication rejection.
$ chmod 600 ~/.ssh/orbvps_node
$ ssh-keygen -F node-address
$ nc -vz node-address 22
$ ssh -vvv -p 22 \
-i ~/.ssh/orbvps_node \
node-user@node-addressConfirm that the username and private key belong to the current node, and check whether another IdentityFile in your local SSH configuration is overriding the key.
Check the address and port shown in the Console, temporarily disable local proxy rules, retest, and record the time and network where the issue occurred.
Keep the complete verbose output and do not repeatedly delete host records. First confirm that the port matches the node delivery details.
Do not simply ignore the warning. Compare the displayed fingerprint with the delivery record in the Console, confirm the node details, and then update the local record.
Read the address, port, and username again from the Console; do not guess from an old terminal history entry.
The private key should generally be readable and writable only by the current user. The SSH configuration and parent directories should not be modifiable by unrelated users.
Retry once in verbose mode, retain the complete output from connection start through the failure point, and redact the address.
Graphical sessions and SSH use separate connection paths. A working SSH connection does not guarantee that the graphical session is configured correctly, so record each symptom separately.
Use only the graphical-session credentials delivered for the current node. After rotating credentials, clear the old password saved by the client to prevent repeated automatic retries.
If you see a black screen or a frozen display, connect first at a lower resolution with a single monitor. Increase the resolution gradually after reaching the desktop to determine whether display settings are involved.
If you can see the lock screen but cannot proceed, first verify keyboard input and focus, then use SSH to check system load and remaining disk space.
Close the client connection deliberately, wait for the session to be released, and reconnect. Do not rapidly create multiple parallel graphical sessions, which can make it unclear which desktop is active.
State whether SSH works, where the graphical client stops, the resolution used, the client’s exact error text, and the time range of the last successful connection. Do not submit the complete access password.
First confirm the Xcode path and version actually being used, then check available signing identities, provisioning profiles, Keychain access, and project caches. Do not upgrade dependencies and replace signing materials during the same investigation.
xcodebuild -version .xcode-select -p to verify the current Developer directory..xcresult; do not submit only the last few lines from the terminal.$ xcode-select -p
$ xcodebuild -version
$ security find-identity \
-v -p codesigning
$ profiles show \
-type provisioning
$ xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Release \
-resultBundlePath Build.xcresult \
buildKeep the command, scheme, configuration, failed target, first error, and its context. Remove repository credentials, tokens, and business data before submitting.
A self-hosted runner showing as online does not mean its job environment is complete. Check the runner process, working-directory permissions, cache usage, concurrent jobs, and automatic recovery after restart.
Confirm that the runner service is still running under the expected user and that its startup arguments point to the correct configuration. If the process repeatedly exits, save the exit code and recent logs first.
ps aux | grep -i runner
Check directory ownership, available space, and lock files from old jobs. Do not delete a working directory that is still being used by a running job.
df -h && du -sh ./work
Distinguish dependency caches, DerivedData, and build artifacts. Locate the problematic cache key first, then clean only the affected project instead of clearing all reusable content.
du -sh ~/Library/Developer/Xcode/DerivedData
Check whether multiple jobs are competing for the same Keychain, simulator, or working directory. After a restart, run one controlled test job before restoring the normal queue.
uptime && sysctl -n hw.memsize
If the test job succeeds but concurrent jobs fail, also provide the concurrency count, job labels, and shared-resource list.
Reduced throughput, slower builds, and a missing external volume can look similar. First collect the system’s built-in diagnostics, then determine whether the issue involves networking, the file system, or the external-device path.
Use the built-in network quality tools to record upload, download, and responsiveness, along with the test time range. Cross-region results can be affected by the local carrier and network path.
networkQuality -v
route -n get default
ifconfigFirst confirm the free space on the system and data volumes, then identify the largest working directories. For build failures, check temporary directories and DerivedData especially closely.
df -h
diskutil list
du -sh ~/Library/Developer/*Check the disk list and Thunderbolt device tree separately. If the device is visible but the volume is not mounted, collect its status first; do not immediately erase or repartition it.
diskutil list external
system_profiler SPThunderboltDataType
diskutil info /Volumes/VolumeNameOrbVPS nodes run normally 365 days a year. Users schedule system upgrades, toolchain changes, and restarts around their own workloads; if urgent infrastructure changes require action, the relevant information will be recorded in the Console.
Record the current macOS, Xcode, and runner versions, key dependencies, and rollback-ready build logs. Do not replace the toolchain without a baseline.
Back up repositories, signing materials, runner configuration, cache policies, and required build artifacts, then verify from an independent location that the backup can be read.
Pause new jobs, wait for running jobs to finish, save the logs, and then restart. Do not change networking, signing, and build settings at the same time during the restart.
Verify SSH, the graphical desktop, disk mounts, the Xcode version, and one controlled build job in sequence before restoring the normal concurrent queue.
Include the node ID, issue time range, affected jobs, commands already run, original output, and redacted screenshots. Existing customers should submit a ticket in the Console; pre-purchase configuration or region questions can be sent through the contact page to support@orbvps.com.