Connection, Migration & Troubleshooting

Connect a Cloud Mac to your existing workflow

First confirm the node and connection details in the console, then start your first session with SSH or VNC. When migration, builds, or MLX services fail, follow this page in order to narrow down the cause instead of guessing across configuration, network, and task logs.

3 stages
Connect, migrate, integrate
2 access methods
SSH and VNC
365 days
Node running normally
Rent a Cloud Mac now Log in to the console
First connection runbook VMKeep / CONNECT
To verify
01
Account and order

Confirm that the order status, node region, machine name, and rental term match.

Console
02
Connection details

Copy the host address, username, and temporary credentials; do not share them with unrelated team members.

SSH / VNC
03
Credential update

Change the password after the first connection and add the team SSH public key.

Required
04
Baseline verification

Record the macOS version, Xcode version, available disk space, and network access results.

Recommended
Keep command output and timestamps before submitting a ticket RUNBOOK-04
First connection path

Establish a reproducible connection baseline first

Do not migrate a repository or install a large dependency set right away. Complete these four basic checks first to confirm the machine identity, connection method, and credential update all work as expected.

  1. 01 Account confirmation

    Verify console details

    Log in to the console and check the order number, node region, machine name, rental term, and connection details. If the node and order do not match, stop before proceeding to avoid migrating files to the wrong machine.

    • Record the order number and node region
    • Confirm the machine name and rental term
    • Read connection details only from the console
  2. 02 Establish a session

    Choose SSH or VNC

    Use SSH first for command-line configuration, automation, and log inspection; use VNC when you need a graphical interface, Xcode settings, or desktop access. Verify both methods once during the first connection.

    • With SSH, verify the host fingerprint and username
    • With VNC, verify the address and display resolution
    • Record the network environment used for the successful connection
  3. 03 Update credentials

    Change the password and add the public key

    Change the temporary password immediately after accessing the machine, then add the team-approved SSH public key to the authorized keys list. Keep keys separate for each member and revoke them individually when they leave the project.

    • Use a unique, sufficiently long password
    • Keep a separate public key for each member
    • Limit distribution of private keys and connection details
  4. 04 Record the baseline

    Verify system and disk status

    Before installing tools, record the system version, Xcode path, available disk space, and basic network results. Compare future failures directly against this baseline.

    • sw_vers View the system version
    • xcode-select -p View the toolchain path
    • df -h View disk space
Migration path

Migrate from a local Mac to a Cloud Mac in three passes

Migration order determines troubleshooting effort. Move verifiable data first, restore fixed toolchain versions second, and connect CI or the self-hosted runner last.

01
Data synchronization

Migrate only what you need

Pull the repository through Git whenever possible. Sync large models, build caches, and artifacts separately, then verify file sizes or checksums after transfer.

Input
Repository, model files, scripts, required configuration
Check
Directory permissions, ignore rules, remaining disk space
Output
A project working copy that can be verified independently
02
Toolchain restoration

Pin Xcode and dependency versions

Confirm the project’s required Xcode, command-line tools, Ruby, Node.js, and CocoaPods versions. Run the smallest build first, then restore the full dependency cache.

Input
Version manifest, lock files, installation scripts
Check
Default Xcode, SDK, runtime, and PATH
Output
A reproducible local build command
03
Automation integration

Register the runner and monitor its first job

Keep the runner work, cache, and log directories separate. Do not parallelize the first job; observe the checkout, build, test, and archive stages first.

Input
Runner registration details and job labels
Check
Execution user, directory permissions, failure exit codes
Output
A repeatable job with traceable logs
Command execution record

Verify SSH, the build, and archiving through one shortest path

The record below demonstrates the troubleshooting sequence and contains no project-specific credentials. Confirm the remote session first, run the Xcode build second, and then check whether the automation tool reports success.

VMKeep build session · zsh SESSION 01
09:14:02 $ ssh vmkeep@203.0.113.24
host vmkeep-m4-plus region JP shell /bin/zsh
09:14:18 $ xcodebuild -workspace Client.xcworkspace -scheme Client -configuration Release build

[1/4] Resolve package dependencies

[2/4] Compile sources and resources

[3/4] Run unit tests

[4/4] Archive build output

09:22:41 $ bundle exec fastlane ios build
Build succeeded
exit=0 · archive=Client.xcarchive · duration=08m23s

If a step fails, retain at least 30 lines of output before and after the failed command, the exit code, Xcode version, and timestamp. Remove tokens, private keys, and signing material before submitting a ticket.

CI/CD integration

Manage the runner, work directory, and cache separately

Continuous build issues usually come from execution identity, directory permissions, version drift, or cache contamination. Confirm these five items before running the first production pipeline.

A1

Register the runner

Register the self-hosted runner under a dedicated execution user and apply clear labels for each build type. Confirm that the runner automatically returns online after a service restart.

Identity and labels
A2

Plan the work directories

Place source checkouts, temporary builds, archived artifacts, and job logs in separate directories so failed jobs do not affect the next run.

Permissions and cleanup
A3

Set cache boundaries

Cache keys should include at least the dependency lock files, Xcode version, and architecture. When unexplained compiler errors occur, rerun once with an empty cache.

Versions and cache hits
A4

Store signing material securely

Inject signing files, passwords, and tokens only at job runtime. Do not write them to the repository, ordinary logs, or long-term shared directories. Remove temporary copies when the job ends.

Minimal exposure
A5

Define failure retries

First distinguish network checkout, dependency resolution, compilation, and test failures. Automatically retry a stage only after confirming that the job is idempotent.

Exit codes and logs
Common CI/CD stages and checks
Stage Check first Results to retain Keep out of logs
Code checkout Repository permissions, remote URL, network resolution Commit hash, branch, failed command Raw access tokens
Dependency installation Lock files, mirror configuration, cache key Tool versions, dependency resolution output Raw private credentials
Xcode build Scheme, SDK, build configuration, target platform Full command, exit code, key error Signing password
Testing and archiving Test target, timeout, artifact directory Test report, archive path, job duration Original signing files
MLX service troubleshooting

Trace results from local inference to the remote API

First prove that the model can complete a request locally on the machine, then check the listening address and port. Do not troubleshoot the remote client before the model loads successfully.

  1. 01

    Confirm the model path

    Check the configured model directory, weight files, and read permissions. Resolve relative paths from the service’s actual working directory.

    test -r /srv/models/model && echo readable
  2. 02

    Monitor memory usage

    Load the model with a single request first and record memory before and after loading. If the process exits, check system logs and the application exit code.

    ps -o pid,rss,command -p <PID>
  3. 03

    Verify local listening

    Confirm the address and port bound by the service. A service listening only on the loopback address cannot accept direct remote connections.

    lsof -nP -iTCP:<PORT> -sTCP:LISTEN
  4. 04

    Send a local request

    Send a minimal request from inside the Cloud Mac and record the response status, time to first token, total duration, and model response.

    curl -sS http://127.0.0.1:<PORT>/health
  5. 05

    Test the remote API next

    After the local request succeeds, verify remote access from an authorized client. Compare the client time, service logs, and request identifier.

    curl -sS https://<YOUR-ENDPOINT>/health
Model compatibility

Whether a specific model runs depends on its format, quantization method, dependency versions, and selected memory configuration.

Performance assessment

Compare time to first token and sustained throughput with the model, parameters, and concurrency held constant.

Ticket evidence

Submit the model path structure, startup command, process logs, listening result, and a redacted minimal request.

Terminology glossary

Eight common connection and troubleshooting terms

Consistent terminology reduces communication gaps across the team. Use the names below when describing the machine, connection method, and job role in a ticket.

Physical node
An Apple Silicon device that actually runs macOS and your jobs, rather than an abstract compute instance.
Dedicated
Each order maps to a separate physical machine, with resources not shared with another tenant on the same instance.
Non-virtualized
The system and jobs run directly on the assigned physical device, without delivery through a shared virtualized instance.
VNC
A remote connection method for accessing the macOS graphical interface, suitable for Xcode settings and desktop operations.
SSH
An encrypted remote connection method for command-line management, file transfer, log inspection, and automation.
self-hosted runner
A self-managed runner registered with the team CI system that executes build jobs on this Cloud Mac.
MLX
A machine learning framework for Apple Silicon, used for model conversion, quantization, inference, and service packaging.
Build cache
Intermediate files retained to reduce repeated downloads and compilation; incomplete cache keys may introduce stale results.
Common connection issues

Check by symptom without skipping the basics

For every issue, verify the order and node first, then check the client, network, and machine state. Expand the relevant item for the recommended sequence and ticket details.

Cannot log in with SSH or VNC

Check sequence:Confirm the order and node details, recopy the host address and username, check the input method and password characters, verify the SSH host fingerprint or VNC address, then retest on a known-working network.

Ticket details:Order number, node region, timestamp, client name, complete error text, and a connection command with sensitive host details redacted.

Connection drops frequently after login

Check sequence:Record the interruption time, test local network stability, disable any proxy that may rewrite routes and retest, inspect SSH keepalive settings, and check whether the interruption coincides with a high-load job.

Ticket details:Interruption window, network environment, consecutive test count, client logs, job type, and system load before and after the interruption.

VNC display is laggy or unresponsive

Check sequence:Lower the display resolution and color quality, pause bandwidth-intensive sync jobs, compare wired and wireless networks, and check whether the issue occurs only at certain times or with a specific client.

Ticket details:Node region, client version, display resolution, local network type, time the lag began, and reproducible steps.

Insufficient disk space or continuously growing build directories

Check sequence:Run df -h to view partitions, then measure DerivedData, archived artifacts, dependency caches, simulator data, and job workspaces by directory. Confirm that artifacts have been exported before deleting anything.

Ticket details:Disk usage results, fastest-growing directories, recently run jobs, cleanup commands executed, and whether a storage add-on should be evaluated.

Build works locally but the runner job fails

Check sequence:Compare the execution user, environment variables, working directory, Xcode version, dependency lock files, and cache keys. Run the same build command manually as the runner user and find the earliest divergence.

Ticket details:Full build command, Xcode version, runner labels, failure exit code, redacted logs, and differences between manual execution and the automated job.

Support options

Organize the evidence first, then choose how to contact us

For existing orders and active node issues, submit a console ticket first. For solution selection, deployment scope, and pre-order questions, email us through the contact page.

Ticket checklist

Information that lets us investigate in one submission

5 ITEMS
Order number

Used to locate the relevant machine and rental term; do not submit your account password.

Node region

Specify Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, or the US East Coast.

Timestamp

Provide a time range with the time zone so connection and job records can be matched.

Command output

Keep the exit code and surrounding error context, and remove tokens and sensitive credentials.

Reproduction steps

Describe the process from the initial state to the issue, noting the expected and actual result for each step.

Existing order

Submit a ticket through the console

For connection issues, machine status, build problems, and billing or order-related questions. The ticket preserves context for adding more redacted logs.

Log in to the console to submit a ticket
Pre-sales and deployment

Prepare an email through the contact page

For configuration choices, team deployment scope, target nodes, and rental-term questions. Our contact email is support@vmkeep.com.

Contact the service team
Next steps

Choose a configuration, then establish the connection baseline

All three tiers of dedicated Apple Silicon physical machines are non-virtualized and available for daily, weekly, monthly, or quarterly rental. Live node availability is determined by the console.

Choose a configuration and rent now View the three rental plans