Cloud Mac Support Center

Identify the failure layer first, then submit diagnostic details

Can't connect, builds fail, or a runner is stuck in the queue? Don't start by reinstalling the environment. Check the order, network, system, and toolchain layers first, then send the key logs to support.

Diagnose VNC, SSH, Xcode, and CI/CD separately
Include the order number, node, time, and complete error context
Remove keys, tokens, and signing passwords from logs

Rent a Cloud Mac now Open the console to submit a ticket

Diagnostic ticket BUILD-SUPPORT

Get ready to troubleshoot

Confirm delivery status Order, node address, and credential sources match

Foundation layer

Separate connection paths Test VNC, SSH, and the local network separately

Network layer

Reduce build variables Pin the scheme, Xcode version, and dependency state

Toolchain layer

Preserve failure context Record the time, command, logs, and steps already taken

Evidence layer

Goal: make the issue reproducible, traceable, and actionable 4-layer diagnosis

Choose an issue type

Six support paths for six troubleshooting starting points

First determine whether the issue concerns connectivity, builds, automation, networking, storage, or billing. Accurate categorization reduces back-and-forth between unrelated logs.

Remote access

VNC display and session

Troubleshoot black screens, timeouts, keyboard layouts, clipboard issues, and interrupted sessions. First record the client name, network egress, and time of occurrence.

Xcode builds

Signing, dependencies, and archives

Check the certificate, provisioning profile, Keychain permissions, DerivedData, dependency cache, available disk space, and export settings.

CI/CD

Runner queue and workspace

Check label matching, service processes, project authorization, concurrency, workspace permissions, and cleanup after failed jobs.

Network

Repositories, dependency sources, and remote access

Separate the local network, node egress, code repository, and dependency download source to avoid mistaking a single service timeout for a fully offline machine.

Storage upgrade

Capacity planning and expansion

First measure usage from projects, DerivedData, dependency caches, archives, and model files, then ask about +1TB, +2TB SSD, or parallel configurations.

Billing

Periods, add-ons, and payment records

Provide the order number, billing period, payment category, and page message. Do not submit complete payment credentials or sensitive information in public email.

Seven-step quick check

Confirm reachability before entering the toolchain

Follow the steps in order. If the previous step is unconfirmed, do not clear caches or reinstall dependencies, or you may overwrite the original failure clues.

01

Check order status

Sign in to the console and confirm that the order is delivered. Make sure the model, term, and node match the instance under investigation. If the order details look wrong, record the order number and page message first.

Order layer
02

Verify the node address

Confirm that VNC and SSH use the address and port in the delivery details. Do not reuse connection settings from an old node, bookmark, or another order.

Addressing layer
03

Confirm account credentials

Check the username, password entry, and keyboard Caps Lock state. Do not paste passwords, private keys, or recovery information into the ticket body.

Access layer
04

Cross-test the VNC client

Record the client name, version, and display-quality settings. If possible, retest from another local device or network to isolate a client-side issue.

Desktop layer
05

Test SSH connectivity

Record where DNS resolution, connection establishment, and authentication each stop. If VNC fails but SSH works, check the graphical session before investigating the entire machine's network.

Network layer
06

Check disk space

Check remaining system-disk capacity, along with DerivedData, dependency directories, archives, simulators, and model files. Low space can trigger many non-obvious build errors.

Resource layer
07

Pin the Xcode version

Record the selected Xcode path and version. Confirm that CI scripts and interactive builds use the same toolchain, then reproduce the failed command once more.

Toolchain layer

Remote access troubleshooting

Separate display, network, and input issues

VNC provides a graphical session; SSH provides a command-line path. Testing them separately quickly shows whether the issue lies with the local client, network path, or node session.

Common remote-access symptoms, first checks, and ticket details
Symptom	What to do first	Record	Avoid
VNC black screen	Wait for the session to initialize, reconnect once, and test whether SSH responds normally.	Client name, time of occurrence, node, SSH test result, and a screenshot of the black screen.	Do not force repeated reconnections or immediately delete system or user settings.
Connection timeout	Retest on another local network, verify the address and port, and distinguish resolution timeouts from authentication timeouts.	Local network type, exact error text, start and failure times, and the retest result on another network.	Do not expose passwords, private keys, or complete authentication details in logs.
Unexpected keyboard layout	Check the local and remote keyboard layouts, input method, and modifier-key mapping using a plain-text editor.	Client, keyboard layout, affected keys, and reproducible steps.	Do not judge only by IDE shortcuts; first rule out the application's own key bindings.
Clipboard unavailable	Confirm that the client permits clipboard synchronization, then test plain text and a short snippet separately.	Copy direction, content type, client version, and whether the issue affects every application.	Do not use keys, tokens, or signing passwords as test content.
Session interrupted	Record the action and duration before the interruption, then check whether SSH remains online and whether the local network changed.	Exact time, foreground application, network changes, reconnect result, and relevant logs.	Do not repeatedly restart build jobs, as this can overwrite resource state from the time of failure.

Xcode build failures

Start with the first actionable error, not the last line

Signing, cache, disk, and export errors often occur in a chain. After pinning the toolchain and reproduction command, trace from the earliest clear failure in the logs.

SIGN

Certificates and provisioning profiles

Confirm that the bundle identifier, team, certificate type, and provisioning-profile purpose match. Do not mix automatic and manual signing in one target without recording the change.

Record the failed target and configuration
Check signing asset validity and scope
Preserve the complete codesign error context

KEYCHAIN

Keychain permissions

When interactive builds succeed but CI builds fail, check whether the runner session can access the required signing items and whether permissions differ in the job context.

Compare the local terminal user with the runner execution user
Confirm the Keychain state at job runtime
Remove signing passwords and sensitive values from logs

CACHE

DerivedData and dependency caches

First confirm that the error is reproducible, then clean only the affected project. Do not treat clearing all caches as the default, or it becomes difficult to identify the cache layer that actually failed.

Record cache directories and hit policies
Pin the lockfile and dependency-manager versions
Keep one build log from before and after cleanup

DISK

Disk space

Archives, simulators, dependencies, and historical artifacts can consume space at the same time. Low space causes not only write failures but also dependency extraction and signing anomalies.

Record remaining system-disk capacity
Check archive and cache usage by project
Confirm which artifacts must be retained before cleanup

EXPORT

Archiving and export

Distinguish archive-creation failures from export failures. For the former, check compilation and signing; for the latter, focus on export options, destination, and signing information in the archive.

State whether the archive was created successfully
Keep the export configuration and error summary
Confirm that the artifact destination matches the scheme

REPRO

Minimal reproduction command

In the ticket, specify the working directory, Xcode version, scheme, configuration, and command. If it fails only in CI, also provide environment differences with sensitive values removed.

Keep at least one context block before and after the error
State whether the graphical-interface build succeeds
List the steps already tried that had no effect

CI runner troubleshooting

Labels decide where a job runs; the workspace decides what remains after failure

If the queue does not move, check labels and online status first. Once a job starts and fails, check the execution user, workspace, concurrency, and cleanup policy.

Runner checklist

Record these four variables together

Executable checks

LABEL Label matching

The labels required by the job must exactly match the runner's registered labels. Also confirm that no project-level or branch-level condition excludes the runner.

WORKDIR Workspace

The directory should be readable and writable by a dedicated execution user. Avoid sharing temporary paths that retain state between projects.

CONCURRENCY Concurrency limits

Set concurrency according to memory, disk, and build type. When too many jobs are present, first determine whether they are queued or already competing for resources.

CLEANUP Cleanup policy

Define what is retained and deleted after each job, and preserve sufficient logs and diagnostic artifacts for failed jobs.

GitHub Actions

Check runs-on and runner groups

Confirm the repository or organization's runner access scope, label spelling, service status, and workspace permissions. If a job is waiting, first check for an online runner with an exact label match.

GitLab CI

Check tags and project authorization

Confirm job tags, runner lock scope, project authorization, and concurrency settings. If the job started and then failed, include executor logs and project-script output.

Other self-hosted runners

Pin execution identity and lifecycle

Specify the runner software, startup method, execution user, workspace, and cleanup script. For custom schedulers, also record job pickup, timeout, and exit-code handling.

Terminology glossary

Eight terms to define the problem clearly

Using the same terminology in support requests prevents physical resources, remote protocols, and automation software from being conflated.

Physical node: An actual Apple Silicon device delivered and running macOS, rather than a virtual instance carved from a shared host.
Dedicated: The computing resources, memory, and local storage associated with the order are used by that customer and not shared with another tenant on the same running instance.
Non-virtualized: The operating system runs directly on physical hardware. Troubleshoot it as a real macOS host with real network and peripheral paths.
VNC: A remote-desktop protocol for accessing the macOS graphical interface. Display, input, and clipboard issues usually start at the client and session layers.
SSH: A protocol for command-line access and automated execution. It helps determine whether the node is online and whether a graphical-session issue is independent.
self-hosted runner: An execution agent deployed by a team on a Cloud Mac to receive CI-platform jobs, with labels and project permissions configured by that team.
Build cache: Dependencies or intermediate artifacts retained to reduce repeated downloads and compilation. Caches need version keys, capacity limits, and a cleanup policy.
Parallel setup: A request for multiple devices or a Thunderbolt 5 connection for suitable workloads. It does not mean every build tool will scale linearly.

Ticket submission guidelines

Give support enough information to start diagnosing immediately

A ticket's value is not its length, but whether the time, target, reproduction steps, and original error are complete.

Ticket materials checklist DIAGNOSTIC PACK

Pre-submission check

Order number and node

State the order number where the issue occurred and the actual node: Singapore, Tokyo, Seoul, or Hong Kong. Label each machine separately when using multiple machines.

Reproduction time

Provide the occurrence time, including the time zone, and the duration. If the issue recurs, list the timestamps from the last two or three occurrences.

Error logs

Keep the context before and after the error, the command, and the exit code. Screenshots can help, but do not replace copyable log text with screenshots.

Steps already taken

List the checks, changes, and retests already completed in order, with the result of each step, so support does not ask you to repeat them.

Expected vs. actual result

Explain what you expected to happen and the stage where the process currently stops. For build issues, include the scheme, Xcode version, and execution method.

Redact before submitting

Remove all authentication materials

Remove passwords, private keys, access tokens, signing passwords, payment credentials, and any other login or authorization data from logs, screenshots, and configuration snippets.

Two contact channels

Tickets are for order issues; email is for general questions

For issues with an existing order, submit a ticket in the console first so it can be linked to the order and node. For general solution advice, email support@macvpsgo.com.

Submit a console ticket View contact options

Support escalation path

Different issues enter different queues

Choosing the right channel is more effective than repeated follow-ups. Hardware and connection issues need an order reference, while general usage questions and business requests are best handled after outlining the use case.

Consultation

Usage and plan consultation

For questions about Xcode versions, CI migration, concurrency, storage needs, and choosing among three configurations.

Go to the contact page

Connectivity

VNC or SSH issues

After completing this page's quick self-check, submit a console ticket with the order number, node, occurrence time, and cross-test results.

Submit a connectivity ticket

Hardware

Suspected physical-node issue

If both VNC and SSH are unreachable, or you can reproduce a disk, network, or device anomaly, stop repeating jobs and preserve the timestamps and logs.

Submit a hardware issue ticket