Cloud Mac Help Center & Troubleshooting Guide

Enter by issue type

Choose a scope first, then follow the shortest check path

Five entry points correspond to different stages of the order lifecycle. Switch categories to see what to confirm first, common causes, and the recommended next step.

Order lifecycle

Ordering & delivery

For payment confirmation delays, missing node details, region or model checks, and first-connection information.

Confirm that the order number, model, rental term, and region in the console match your submission.
After payment is confirmed, the system performs node allocation, health checks, and connection information generation in sequence; the typical process takes about 4 minutes.
If connection details are still unavailable after the typical time, do not create another order; record the order number and submit a ticket.

Quick diagnosis

First checks for five common failures

Each card follows the order: confirm the status, narrow the variables, then preserve evidence. Change only one variable at a time so you can identify what restored the service.

Cannot connect to the node

Confirm in the console that the node is operating normally.
Check the address, port, username, and connection protocol one by one.
Test the same port from another network to rule out local egress or firewall restrictions.
Record the client’s exact error message and the time it occurred; do not repeatedly try large numbers of passwords.

View the remote access guide

Build suddenly fails

Record the failed submission, build command, exit code, and first actionable error.
Run xcodebuild -version to confirm the current toolchain.
Check whether lockfiles, environment variables, or signing assets have changed.
Only clear the relevant cache after confirming a cache issue; do not delete all evidence first.

Open the Xcode troubleshooting steps

Insufficient disk space

Use df -h to check volume capacity, not just a single directory.
Check DerivedData, archives, simulator data, and package-manager caches.
Delete rebuildable content first, then handle build artifacts and project files.
Add consistently growing directories to pipeline cleanup rules and set up capacity monitoring.

View the safe cleanup order

Credentials no longer work

Determine whether the failure involves system login, an SSH key, a repository token, or signing permissions.
Confirm the credential’s validity period, file permissions, and the identity of the user invoking it.
After rotating credentials, update pipeline variables and revoke the old values.
Do not paste complete credentials into shell history, screenshots, or ticket content.

View security and permissions guidance

Network latency or jitter

Record your local city, carrier, node region, and the time the issue occurred.
Run multiple consecutive tests and use the median; do not draw conclusions from a single spike.
Check interactive latency, packet loss, and large-file transfer throughput separately.
Disable unnecessary audio/video and high-color-quality settings, then compare the VNC experience.

View connection optimization methods

Core terminology

Understand node, connection, and build context

The definitions below reflect how these terms are used in this service. Using consistent terminology in tickets reduces repeated clarification of the issue scope.

Physical node: An independent Mac mini device that runs workloads. It has a defined chip, memory, storage, and region, and is not a shared compute instance.
Dedicated: During the rental term, the node’s compute resources are assigned to the current order and are not scheduled together with other customers’ workloads, providing clearer performance and environment boundaries.
VNC: A remote display protocol for accessing the macOS graphical interface. It is suitable for desktop operations, viewing Xcode, or adjusting system settings.
SSH: A protocol for encrypted command-line connections. It is suitable for running scripts, transferring files, managing runners, and troubleshooting tasks that do not require a graphical interface.
self-hosted runner: An executor managed by your team and connected to a code-hosting pipeline. Jobs run on a specified Cloud Mac, while the team controls the toolchain, cache, and concurrency strategy.
Code signing: The process of using certificates, private keys, and provisioning profiles to verify an app’s origin and authorization scope. Restrict access to these assets, rotate them regularly, and keep them out of repositories.
Build cache: Data used to reuse dependencies, compiled intermediate results, or downloaded tools. It can shorten build times, but incorrect or stale caches can cause inconsistencies.
Node region: The data-center region where the Mac mini is located. The current directory covers 6 regions: Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, US East, and US West.

Delivery & credentials

From order confirmation to your first secure login

Typical delivery takes about 4 minutes and consists of four consecutive steps. Actual availability and connection details are provided in real time by the console.

01

Order & payment confirmation
About 1 minute

Verify the model, rental term, node region, and add-ons. Once payment is confirmed, the order enters allocation; do not try to speed up processing by paying again.
Save: order number, payment result identifier, and submission time.
02

Node allocation
About 1 minute

The system assigns an independent Mac mini physical node according to the order catalog. Both models are available in Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, US East, and US West.
Check: node ID, model, and region.
03

Node health check
About 1 minute

Before delivery, the system checks startup, network connectivity, and remote access services. All nodes operate normally 365 days a year.
Wait for: the console status to change to Connectable.
04

Connection details delivered
About 1 minute

The console provides the address, port, username, and temporary credentials. After your first login, immediately update the temporary password, configure a dedicated SSH key, and store credentials in a controlled secrets manager.
Complete: first login, password update, and SSH key verification.

Credential boundaries

Do not submit private keys, complete passwords, or complete access tokens in screenshots, repositories, build logs, or tickets. When describing a credential type, provide only its purpose, creation time, and a few trailing characters.

Xcode troubleshooting path

From version baselines to reproducible logs

Do not start by clearing every cache or reinstalling the toolchain. Confirm versions and paths first, check signing assets next, and perform narrowly scoped cleanup last.

01

Confirm Xcode and macOS versions

Record the versions shown in the graphical interface, then run the commands as the pipeline user. If an interactive local build succeeds but the runner fails, also compare their execution users and environment variables.

xcodebuild -version
sw_vers
whoami

02

Confirm the selected command-line tools

Use xcode-select -p to check the current developer directory. When the team maintains multiple versions in parallel, explicitly select the path at pipeline startup to avoid changes to the system default.

xcode-select -p
xcrun --find xcodebuild
xcrun xcodebuild -version

03

Check certificates and provisioning profiles

Confirm that the signing certificate has not expired, the private key is readable by the build user, and the provisioning profile matches the target identifier. If automatic signing fails, preserve the original error first, then check Keychain permissions and pipeline variables.

security find-identity -v -p codesigning
ls -la ~/Library/MobileDevice/Provisioning\ Profiles

04

Clean DerivedData selectively

Delete the directory for the current project first instead of clearing all project caches. Record disk usage and failure logs before cleanup to determine whether the cache actually caused the issue.

du -sh ~/Library/Developer/Xcode/DerivedData
find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -type d

05

Collect xcodebuild logs

Keep the complete command, exit code, and first actionable error. Before submitting a ticket, remove repository tokens, signing secrets, username paths, and internal addresses, but do not capture only the final line.

set -o pipefail
xcodebuild test 2>&1 | tee build.log
printf "exit=%s\n" "$?"

Support request guidelines

Give support engineers what they need to reproduce the issue

A complete request does not mean uploading all your data. The goal is to provide a clear timeline, affected scope, and redacted technical evidence.

Recommended ticket structure

Node ID: Copy the exact identifier from the console; do not replace it with a custom device nickname.
Time of occurrence: Specify the date, time zone, start time, and most recent time the service worked normally.
Node region: Enter the region shown in the order, not only the city where you are located.
Impact scope: State whether the impact affects a single command, one pipeline, all connections, or the entire team.
Reproduction steps: List commands, inputs, expected results, and actual results in the order they were performed.
Checks completed: Describe each action and its result; avoid writing only “I tried everything.”

Log redaction rules

Replace access tokens, passwords, and private-key contents with clear redaction markers.
You may retain the repository-hosting platform type, but remove organization names, project names, and authentication parameters.
Replace user directories with generic paths while preserving the relative directory structure.
For certificate issues, provide the name, validity period, and error message without submitting the private key.
For payment issues, provide the order number and result identifier without submitting complete payment information.
Before taking screenshots, check shell history, the menu bar, filenames, and notification contents.

Do not upload

Private keys, complete login credentials, complete access tokens, unredacted environment variables, or configuration files containing sensitive parameters.

When should I skip self-service checks and submit a ticket immediately?

Stop repeated attempts and submit a console ticket immediately if you see unusual credential activity, an unexpected host-fingerprint change, a clear mismatch between node status and actual connectivity, or any situation where further actions could damage evidence.

Why does node operation require order ownership verification?

Resetting access, changing node status, or handling sensitive configuration can affect a dedicated physical node. The support team must verify the login session, order number, and authorization relationship to prevent unauthorized node-level requests.

If connection and build failures occur at the same time, should I submit one ticket or multiple tickets?

If both occur at the same time and may result from the same node status, list the connection and build evidence separately in one ticket. If the time, node, or scope of responsibility differs, submit separate tickets for independent tracking.

Escalate to support

Submit a trackable request with diagnostic results

Submit existing-order, node-connection, build-failure, and billing issues primarily through console tickets. For presales evaluation, team deployment, and security reports, use the contact page with support@hexvm.com. Node operations require order ownership verification.

Open the console to submit a ticket View ways to contact the team Read the remote access guide

Cloud Mac Help Center