Engineering Support Handbook

Get your Cloud Mac running, from first connection to troubleshooting

Follow this executable checklist: verify your order and node details, establish a remote connection, configure your development toolchain, connect continuous integration, then collect logs and submit a ticket based on the symptoms.

Submit a ticket in the console View support options

Node regions: Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong
Service operation: Operating normally 365 days a year
Support channels: Console tickets or support email

Find the right path first

Six issue types, six shortest paths to resolution

If an issue spans multiple categories, start with “First connection” to verify the basics, then move to “Troubleshooting.” Actual account, order, and node status is determined by the console response.

First connection

Don’t start by reconnecting repeatedly—complete these five basic checks first

During first use, the most common issues are incorrectly copied node details, local network restrictions, or unsuitable display settings. Checking in order prevents environment issues from being mistaken for node problems.

01

Read the current order details in the console

Confirm that the order number, model, node region, connection address, username, and access credentials all belong to the same order. Do not use old order screenshots or historical information from chat records. Store credentials only in a controlled password manager.
Acceptance criterion: model and region match the current order
02

Establish a remote desktop connection

Use a remote desktop client that supports the macOS graphical interface, and enter the connection address and username exactly. If the connection fails, switch local networks once to rule out the effects of a corporate proxy, egress firewall, or public-network policy.
Acceptance criterion: the macOS graphical interface is visible and the desktop is usable
03

Complete the basic security setup

After your first login, change the system password, check the screen-lock timeout, and confirm that project private keys, signing credentials, and access tokens are not written to shared scripts, command history, or public repositories. Never send passwords or private keys to support staff.
Acceptance criterion: access credentials have been changed and securely stored by the team
04

Adjust resolution and image quality

Choose an appropriate scaling factor for your local display. When the network fluctuates, reduce image quality and resolution first, then assess node response; mouse lag and a blurry image do not necessarily indicate lower compile or disk performance.
Acceptance criterion: text is clear, and input and window dragging respond consistently
05

Run the first-login checks

Open Terminal and verify the system time, available disk space, network resolution, and Xcode command-line path. Then create a temporary directory and test writing, reading, and deleting files to confirm that the current user has the permissions required for the project directory.
Acceptance criterion: time, disk, network, and directory permissions are all normal

Development environment

Fix versions and directories before installing project dependencies

A Cloud Mac is a dedicated physical machine, not a virtual machine. Your team should still document the environment as a reproducible checklist to prevent accumulated manual changes from making it impossible to restore.

Xcode

Pin the toolchain version required by the project

Read the version requirements in the project documentation and CI configuration first, then select the corresponding Xcode version. After switching, also check the compiler path, SDK list, and command-line tools so the GUI version matches the path actually used by Terminal.

xcode-select -p
xcodebuild -version
xcrun --show-sdk-path

Validation: the Xcode major version, SDK, and tool paths reported by local development and continuous integration match.

Homebrew

Manage reproducible dependencies with a Brewfile

Do not rely on personal memory for the list of installed tools. Export a Brewfile from the existing environment, remove unrelated packages, then install from the checklist on the Cloud Mac. Inject private-source access tokens through controlled environment variables.

brew bundle dump --force
brew bundle check
brew bundle install

Validation: the Brewfile runs in a clean directory without requiring sensitive tokens to be written to the repository.

Git

Separate repository identity from project permissions

Check the username, commit email, default branch, and line-ending rules. When projects use different repository permissions, configure separate key files and host aliases instead of letting one highly privileged credential cover every build task.

git config --global --list
git remote -v
ssh -T git@your-git-host

Validation: pulls, commits, and submodule access use the expected identities separately, and logs do not output tokens.

Signing & command line

Keep sensitive materials outside the build process

Import certificates, private keys, and signing credentials through a team-approved secure process, with least-privilege access configured per project. Pin Node, Ruby, Python, CocoaPods, and other tool versions, and commit the version files to the repository.

node --version
ruby --version
python3 --version
pod --version

Validation: a new session can restore the environment from the version files, and build logs contain no credential contents.

CI/CD integration

Use your Cloud Mac as a traceable, persistent build node

When adding a GitLab CI Runner, define the node’s role before registering the executor. One node can handle multiple queues, but high-privilege signing tasks and regular compilation tasks should use separate tags, directories, and credential scopes.

Install and register the GitLab CI Runner

Complete installation with the registration details assigned to the project or team. Set tags that describe the node architecture, Xcode version, and task type; disable untagged jobs to prevent arbitrary pipelines from using the build node.

Record the Runner name and assigned project
Tags include the toolchain and task type
Verify the execution user’s directory permissions

Persistence

Manage persistent build jobs

Run the Runner as a controlled background task and confirm that it recovers after a restart. Do not keep build processes running indefinitely in a personal terminal session; a disconnected session should not interrupt an active compile or test.

Check the process owner and startup method
Limit the number of concurrent jobs
Set exit rules for timed-out jobs

Caching

Fix the cache directory and cleanup boundaries

Keep dependency caches, DerivedData, archives, and final artifacts separate. Caches can be reused, archives must be tracked, and temporary files should be cleaned up per pipeline. When disk usage grows unexpectedly, locate the directory first instead of deleting unknown project data.

Record cache and artifact paths separately
Use an independent directory for each project
Check available disk space and growth sources regularly

Isolation

Isolate signing credentials and repository permissions

Inject least-privilege credentials per project and restrict signing jobs to protected branches. Logs should record only whether credentials loaded successfully—not passwords, private keys, tokens, or signing material.

Protect sensitive variables and restrict branches
Use separate tags for regular builds and signing jobs
Clean up temporary files after each job

Integration acceptance

Validate with one minimal pipeline instead of migrating every job at once

Clone a test repository containing no sensitive data.
Output the Xcode, SDK, and dependency-tool versions.
Run one unsigned build and save the artifact.
Check the cache, logs, and temporary directory after the job exits.

Service availability

Use consistent metrics to assess service status—not a single network fluctuation

MacMLab Cloud Mac nodes operate normally 365 days a year. Connection quality is also affected by the user’s local network, egress policies, remote desktop settings, and workload. Record these factors separately from node status during troubleshooting.

Service availability metric: 99.9%
Observation period: 90days

If the order meets the applicable conditions and verification confirms a platform service issue, compensation will be handled under the service terms and the relevant order records.

Daily status bars for the past 90 days Daily records help assess continuity; current status and order information are based on the console’s actual response.

Normal operation records From earlier records to the most recent

Troubleshooting decision tree

Start with the symptom and change only one variable at a time

Record the occurrence time and original error first, then run the checks. Do not reinstall tools, switch networks, and clean directories at the same time; otherwise, even if the issue clears, you cannot confirm the root cause.

Start

Can the node establish a remote connection?

First confirm the order status, node region, and connection details in the console, then choose the branch below that best matches the symptom.

Unable to connect

Address unresponsive or credentials rejected

Confirm that the connection details come from the current order.
Switch local networks and pause the proxy, then test again.
Record the client’s original error message and occurrence time.

Submit:order number, node region, local network type, error screenshot, and client name.

Slow response

Laggy display, delayed input, or slow tasks

Lower the remote desktop resolution and image quality.
Distinguish desktop display latency from Terminal command duration.
Check CPU, memory, disk, and concurrent jobs.

Submit:slow operation name, start and end times, concurrent job count, and a redacted resource summary.

Disk space

Write failures or continuously declining free space

Check the sizes of project, cache, archive, and log directories.
Check whether failed jobs left temporary files behind.
Clean only rebuildable caches; do not delete unknown data.

Submit:available disk space, fastest-growing directory, recent jobs, and redacted results from before and after cleanup.

Build failure

Compiler, dependency, or signing workflow error

Record the Xcode, SDK, and dependency-tool versions.
Reproduce the minimal build task in a clean directory.
Compare environment-variable names locally and in CI.

Submit:failed command, exit code, first actionable error, and relevant redacted log excerpts.

Node issue

Multiple independent operations fail at the same time

Rule out a single repository, tool, or client.
Record symptoms shared by Terminal and the graphical interface.
Stop repeated retries and preserve the current state.

Submit:order number, node region, incident timeline, scope of impact, and the most recent successful operation.

Contact support

Use tickets for technical issues; email support for general questions

MacMLab provides only two external support channels: console tickets and support email. For existing order, node, or billing issues, submit a ticket first so the order record and ongoing status updates can be linked.

Recommended path

Log in to the console and submit a ticket

Suitable for connection failures, node issues, build environments, billing status, and order-related questions. Start the ticket with the conclusion, then list reproduction steps in chronological order.

Suggested title Node region + symptom + first occurrence time

Body order Order number → scope of impact → reproduction steps → original error → checks already performed

Attachment requirements Upload only redacted screenshots and log summaries; cover passwords, private keys, tokens, and signing credentials

General inquiries

Send a support email

Suitable for configuration questions before ordering, enterprise requirements, documentation feedback, or cases where you cannot log in to the console.

support@macminilab.com

Privacy reminder

Support staff do not need your secrets

Do not send system passwords, private keys, access tokens, signing credentials, or complete business data. Preserve error context in logs while replacing repository addresses, usernames, and key contents.

View data handling information

Prepare your order number and reproduction steps before handing the issue to support

For existing orders, submit a ticket through the console. If you are still evaluating models, rental periods, or the four node regions, review the two plans and billing structure first.