Connection / Toolchain / Diagnosis

Complete the remote connection,
then troubleshoot layer by layer.

This guide is for connecting to a dedicated physical node: first verify the node address and system credentials, then configure SSH, VNC, Xcode, and the CI runner. When issues occur, troubleshoot in this order: network, authentication, system, toolchain, and storage—to avoid unproductive retries.

Open the console to view the node View cloud Mac plans
Connection methods SSH / VNC
System interface GUI / CLI
Resource type Dedicated physical machine
Node operation 365 days

01 / First connection

Verify these five types of information before connecting

Do not guess at the network or reset the system first. The node record in the console is the single source of truth. When copying an address, do not include a protocol prefix, spaces, or any characters other than the port.

  1. 01

    Node address and region

    Confirm the instance's node ID, region, host address, and connection port. The region should match the order. If your team uses a network allowlist, also record the client's current public egress IP address.

    Check: NODE ID / HOST / REGION / PORT

  2. 02

    System account

    Account names are case-sensitive. The account name in the SSH command, the VNC login dialog, and the value shown in the console must match. Do not substitute an email address for the system username.

    Format: username@host

  3. 03

    Temporary credentials

    Before first use, confirm that the credentials match the current version shown in the console. Change the temporary password immediately after signing in. If the password has already been changed, use the new value; the old one is no longer valid.

    Action: Sign in → Change → Store securely

  4. 04

    SSH client

    On macOS and common Linux environments, you can use the terminal directly. Check port connectivity first, then start SSH. When a host fingerprint appears for the first time, verify the node address before confirming it.

    Recommended: 10s connection timeout / 30s keepalive

  5. 05

    Screen Sharing or VNC client

    Prepare a VNC-compatible client and confirm that the connection target includes the correct port. For the first connection, start with a lower resolution and adaptive image quality; increase display settings after confirming stable input.

    Starting point: 1920×1080 / 24-bit / Adaptive

Recommended verification order:Use SSH first to verify the address, port, account, and credentials, then connect to the graphical interface. If SSH works but VNC fails, narrow the investigation to the graphical service, VNC port, and client settings.

02 / Glossary mini

Standardize terminology before checking configuration

These terms appear in orders, the console, connection documentation, and incident records. Each one refers to a clearly defined resource boundary or technical action.

Physical node
The Mac mini hardware that actually runs macOS. The node address, region, and node ID together identify the resource delivered to you.
Dedicated
A single tenant uses the device's entire chip, memory, and storage; the operating system instance is not shared with other tenants.
Cloud Mac
A Mac deployed on a remote node and accessed over the network. MiniDeploy provides dedicated physical machines, not virtual machines.
VNC
A protocol for transmitting a remote graphical interface, keyboard input, and pointer actions. Experience is mainly affected by round-trip latency, resolution, color depth, and the amount of screen change.
SSH
An encrypted connection method for remote command-line access, file synchronization, and automation, suitable for environment checks, builds, and log collection.
self-hosted runner
An execution endpoint managed by your team that receives CI jobs. You can pin the Xcode version, cache paths, working directory, and build dependencies.
Toolchain
The set of Xcode, command-line tools, package managers, Ruby, fastlane, scripts, and environment variables required to complete a build.
Node latency
The round-trip time for data between the client and node, usually measured in milliseconds. Lower values generally mean more responsive remote desktop input.

03 / Terminal mock

Validate connectivity, builds, and uploads with three output blocks

Terminal output should answer three questions: Are you on the correct node? Is Xcode using the expected version? Has the build artifact been received by the pipeline?

The hostname in this example only illustrates the command structure. Use the address, port, account, and node ID recorded in the console. When collecting logs, retain timestamps and failed commands, and remove passwords, private keys, and signing materials.

04 / Migration path

Three-step migration path from a local Mac to a cloud Mac

Do not migrate every directory at once. Move project data first, replicate the toolchain next, and connect CI last. Set a verifiable completion condition for each step.

  1. STEP 01

    Sync the project and configuration checklist

    Prioritize syncing the code repository, build scripts, and required resources. Transfer large files separately and calculate checksums before and after transfer. Do not copy all caches from the old machine directly.

    • Record the repository branch and commit hash
    • Export the dependency version list
    • Verify the number and size of critical files
    Acceptance criteria Code can be checked out and the dependency list can be read
  2. STEP 02

    Replicate Xcode and the signing toolchain

    Record the Xcode major version, command-line tools path, Ruby version, and fastlane version. Import signing materials through a controlled process, then check file permissions and validity scope.

    • Confirm xcode-select -p
    • Pin package manager and script versions
    • Run one local Release build
    Acceptance criteria The same commit can be archived reliably
  3. STEP 03

    Connect the self-hosted runner

    Give the runner a dedicated working directory and service account. Limit label matching, set the concurrency level, and separate cache, log, and artifact paths from the source directory.

    • Run a minimal test job after registration
    • Verify cache-hit and cleanup rules
    • Confirm that failed logs can be returned
    Acceptance criteria The commit-trigger, build, and result-return loop is complete

05 / Remote desktop

Start remote Mac desktop settings with a low-load profile

Remote desktop experience depends on more than bandwidth. Node latency, resolution, color depth, frame rate, client scaling, and background file transfers all affect input responsiveness.

macOS Screen Sharing

Suitable for entering the graphical interface from a Mac client. Use the host address and port provided in the console, and ensure the login account exactly matches the system account.

Initial resolution
1920×1080
Color depth
24-bit
Recommended available bandwidth
≥ 15 Mbps
Interaction guidance
Prefer adaptive quality

If the display lags, stop background synchronization first, then lower the remote resolution. Do not change resolution, color depth, and compression level at the same time, or it will be difficult to identify the actual cause.

General VNC client

Suitable for cross-platform access. Enable adaptive compression and disable unnecessary animations. If the client lets you control image quality and color depth separately, keep image quality automatic and lower only the color depth first.

Initial resolution
1600×900
Color depth for weak networks
16-bit
Recommended available bandwidth
≥ 10 Mbps
Keepalive
30–60s

When input is noticeably delayed but the image remains clear, check the round-trip latency between the client and node first. Higher resolution will not fix network jitter; it only increases encoding and transfer overhead.

Use case Starting resolution Color depth Recommended bandwidth First adjustment
Terminal and light editing 1600×900 16-bit ≥ 8 Mbps Reduce dynamic content
Xcode coding and debugging 1920×1080 24-bit ≥ 15 Mbps Maintain a low-latency path
Multi-window development 2560×1440 24-bit ≥ 25 Mbps Confirm stability first
Frequent screen changes 1920×1080 24-bit ≥ 30 Mbps Lower frame rate or quality

Bandwidth figures are starting points, not conclusions about latency. When using a remote desktop mainly for development and administration, choose a node close to the client and validate it under the actual network conditions.

06 / CI/CD

Make the runner reproducible—not just a one-time success

CI is not complete when you see one green result. The same commit should build again after the working directory is cleaned, with enough logs retained when it fails.

Registration

Runner registration

  • Run it with a dedicated service account
  • Use labels that distinguish at least the architecture and Xcode version
  • Set default concurrency to 1, then adjust after confirming the load
  • Use the registration token only during configuration
Workspace

Isolate working directories

  • Use a separate checkout directory for each job
  • Store source, caches, logs, and artifacts separately
  • Clean up temporary files after each job
  • Do not let different projects share writable configuration files
Cache

Caching strategy

  • Include a dependency lockfile digest in the cache key
  • Set cache size limits and expiration conditions
  • Allow a full rebuild when cache hits behave unexpectedly
  • Do not cache signing materials or short-lived credentials
Signing

Build certificates

  • Import only the materials required by each project
  • Restrict file permissions and accessible accounts
  • Record expiration dates and check them in advance
  • Task logs must not output sensitive content
Logs

Log retention

  • Retain the job ID, commit hash, and timestamp
  • Save standard output and standard error
  • Upload a diagnostic summary when a stage fails
  • Redact data before submitting it to support
Validation

Minimal acceptance task

  • Output the system and Xcode versions
  • Fetch dependencies and run unit tests
  • Generate an identifiable build artifact
  • Run it again after cleaning the directory
Resource boundary:The M4 Core configuration includes a Mac Mini M4, 16GB RAM, and 256GB SSD. Parallel jobs consume memory, storage I/O, and network capacity at the same time. Measure the peak usage of one job before connecting multiple pipelines instead of simply increasing concurrency.

07 / Diagnosis tree

Enter the troubleshooting tree by symptom

Change only one variable at a time, recording the timestamp, command, return value, and client network. Repeatedly clicking the connect button usually adds no useful information.

Cannot connect: determine whether the address or port is unreachable first
  1. Confirm in the console that the node status, address, region, and port are correct.
  2. Check whether the local network restricts the target port. Switch networks only for comparison, not as a long-term solution.
  3. Use port probing to determine whether the result is a timeout, refusal, or successful connection, and record the exact timestamp.
  4. If both SSH and VNC are unreachable, provide the node ID, client city, network operator, and probe results.
  5. If SSH is reachable but VNC is not, continue by checking the VNC port, client target format, and graphical service status.
Authentication failed: verify the account, credential version, and input method
  1. Confirm that you are using the system account name—not an email address, node ID, or device name.
  2. Recheck the temporary credentials in the console. If the password was changed, use the updated credentials.
  3. Check the keyboard layout, letter case, leading and trailing spaces, and special-character input. Avoid copying from rich text.
  4. If SSH key authentication fails, check that the public key was added to the correct account and verify directory and file permissions.
  5. Stop retrying after repeated failures. Record the client, timestamp, and response, then submit a support ticket.
Display lag: distinguish high latency, insufficient bandwidth, and background usage
  1. Measure round-trip latency from the client to the node first, and watch continuously for noticeable jitter or packet loss.
  2. Pause code synchronization, dependency downloads, and large-file uploads to see whether input responsiveness returns.
  3. Lower the resolution to 1600×900, lower the color depth to 16-bit, and leave all other settings unchanged.
  4. Disable animated desktops, transparency effects, and high-refresh-rate windows to reduce screen changes.
  5. If the issue occurs only with a specific client, compare it with another client and record both versions.
Build failed: narrow it down by version, dependencies, permissions, and environment variables
  1. Output the current Xcode version, command-line tools path, architecture, and target SDK.
  2. Verify the dependency lockfile, clear project-derived data, and run one complete build.
  3. Compare the Ruby, fastlane, package manager, and script versions locally and on the node.
  4. Check that the working, temporary, and artifact directories have the correct read/write permissions.
  5. Save the first actual error and the surrounding logs; do not submit only the final exit code.
Insufficient disk space: locate the growing directory, then perform reversible cleanup
  1. Check the remaining space on the system volume, then measure source, cache, derived-data, simulator-data, and archive sizes by directory.
  2. Delete regenerable project caches and temporary files from failed jobs first.
  3. Set a retention count for CI working directories to prevent old checkouts and artifacts from accumulating.
  4. Sync long-term artifacts to team storage, verify the checksum, then delete the node copy.
  5. If the workload consistently exceeds the 256GB SSD capacity, evaluate a storage add-on when ordering.

08 / Security operations

Treat the first connection as a security handoff

A dedicated physical machine provides a clear resource boundary, but your team should still manage accounts, keys, project files, and access sources inside the node according to least-privilege principles.

Change temporary credentials

Set a new strong password immediately after the first sign-in and store it in your team's approved credential manager. Do not share passwords through build logs or ordinary documents.

Restrict remote access sources

Limit SSH and VNC exposure to the team's actual egress addresses. Update the rules when member networks change, and do not retain temporary test sources indefinitely.

Use least-privilege accounts

Use separate, clearly scoped accounts for daily builds, remote operations, and the runner service. Elevate privileges temporarily only for installation or system configuration, then exit promptly.

Remove temporary keys

After migration, troubleshooting, or external collaboration ends, delete temporary public keys, short-lived tokens, and test accounts. Also check whether automation scripts still reference old credentials.

Log redaction boundary:You may retain the node ID, timestamp, command name, exit code, and error stack. Remove passwords, private keys, access tokens, signing materials, complete environment variables, and sensitive business data from projects.

09 / Support escalation

Submit reproducible details so support can start troubleshooting immediately

For technical issues, submit a ticket through the console first so it can be linked to the instance and updated with additional logs. If you cannot access the console or need a pre-sales confirmation, send an email.

Console ticket

Best for node and connection issues

After signing in to the console, open the ticket area, create a technical support request, and link the relevant node. Keep each ticket focused on one primary issue rather than combining unrelated problems.

  • Node ID and region
  • Incident time with time zone
  • Client city, network, and connection method
  • Shortest reproduction steps and expected result
  • Redacted command output and logs
Sign in to the console to submit a ticket
Support email

Best for account access and pre-sales questions

Use “issue type + node ID or order identifier” as the email subject. Describe completed checks in chronological order, and do not send passwords, private keys, or unredacted signing materials.

  • Contact email and time zone
  • Issue scope and priority
  • Troubleshooting steps already completed
  • Times available for troubleshooting
  • Specific questions requiring confirmation
Before submitting Reproduce the issue once and record the exact time
When submitting Include the node ID and redacted logs
After submitting Continue adding information to the same ticket

Ready to connect

Have the node details ready? Start in the console

Copy the node address, system account, and current credentials, complete one SSH verification, and then open the remote Mac desktop. Need another dedicated physical machine? View fixed configurations and term pricing.

Connect through the console View pricing and specifications