Connect first. Then test.

Run commands over SSH.
Use VNC for the desktop.

You’re connecting to a dedicated physical Mac, not a virtual machine. Start by opening the machine details in the portal to find its IP address, connection ports, and credentials. Use SSH for builds and tests, and VNC to work with the macOS desktop. You can use both together; there’s no need to run every build from a remote desktop.

Rent a cloud Mac Sign in to view credentials

Already placed an order? Make sure your machine has been delivered before connecting. Use the port, username, and authentication method shown for your instance—don’t rely on example values.

Choose the right tool for the job

SSH for builds. VNC for desktop issues.

First, establish a reliable command-line connection, then open the desktop. This makes it easier to isolate network and authentication issues, while keeping desktop refreshes from competing with build logs for bandwidth.

SSH: run commands on your Mac

Use SSH to run xcodebuild, execute scripts, inspect logs, and manage build artefacts. You can connect from Terminal on macOS, OpenSSH in Windows Terminal, or an SSH client on Linux.

  • Get the SSH port from your instance details. Port 22 is a common default, but your instance may use a different port.
  • Verify the host key on your first connection. Confirm that it’s the right machine before authenticating.
  • Set up public-key authentication. Keep your private key local—don’t put it in a project repository or attach it to a support ticket.
  • Run long jobs in a persistent session or pipeline runner you’ve configured. Don’t rely on your local terminal staying connected to keep a job running.
See SSH and build examples

VNC: work directly on the macOS desktop

Use VNC to adjust project settings, inspect the simulator, and investigate issues that only appear in a graphical interface. Compatible clients include macOS Screen Sharing and RealVNC. Authentication support depends on your client and instance settings.

  • Enter the instance IP address and VNC port in your client. Don’t use the SSH port for a desktop connection.
  • Use the desktop credentials shown in your instance details. Don’t assume they use the same authentication method as SSH.
  • For your first connection, try a resolution of 1440 × 900, then adjust it to suit your screen and network.
  • If your client supports it, start with 16-bit colour. Increase the image quality when you need to inspect colour details.
See desktop tuning tips

VNC isn’t a substitute for connecting local USB devices. You can plan simulator testing and remote desktop access directly; for tests that depend on external devices, confirm the connection requirements before choosing a plan.

From connection to test results

Verify the host key before running build commands

This is an illustrative log, not a live result from a current location. Set the environment variables to your instance’s actual values before running the commands. App is an example scheme name; replace it with one that exists in your project.

metalvnc — tokyo-node — zsh 
$ ssh -p "$SSH_PORT" "$MAC_USER@$MAC_IP"

The authenticity of host cannot be established.
ED25519 key fingerprint is displayed by your SSH client.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
yes
Authenticated using publickey.

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer

$ xcrun simctl list devices available
== Devices ==
Available simulators are listed by the installed runtime.

$ xcodebuild -scheme App -destination 'platform=iOS Simulator' test
Test Suite 'AppTests' started.
Executed 128 tests, with 0 failures.
** TEST SUCCEEDED **

$ fastlane beta
Build processing completed.
Upload completed successfully.
fastlane finished successfully.

Read the output in this order: confirm SSH authentication → check the toolchain → check the simulator → run tests → check the build and upload results.

The 128 passing tests and 0 failures are examples to help explain the log. Your actual test count, run time, and upload results depend on your project.

If the host key doesn’t match, stop and verify it

On your first connection, compare the fingerprint shown in your terminal with a record from a trusted source. If the instance details don’t include a fingerprint, confirm it through a portal support ticket. If you later see a warning that the host identity has changed, don’t delete the old record to bypass the check. First confirm whether the machine was reinstalled or replaced.

A working command line doesn’t mean your project is ready

Before running tests, check the Xcode path, simulator runtime, project dependencies, and shared scheme. fastlane beta requires a matching lane, signing assets, and upload credentials in your project. It isn’t a universal upload command that works with any project.

Compare locations on equal terms

Measure round-trip latency before judging desktop responsiveness

Available locations: Singapore, Tokyo, Seoul, and Hong Kong. The network route between you and a location often matters more than the geographic distance. Results can also vary between providers in the same city.

Data status: There are no verifiable city-by-city samples available at present, so the table is marked “Not sampled” rather than presenting estimates as measured medians. Test from your own network before choosing a location. For an advance assessment of the route, contact us by email or submit a support ticket through the portal.

Source city × destination: median ICMP round-trip latency, in ms
Test locationSingaporeTokyoSeoulHong Kong
ShanghaiNot sampledNot sampledNot sampledNot sampled
ShenzhenNot sampledNot sampledNot sampledNot sampled
TaipeiNot sampledNot sampledNot sampledNot sampled
BangkokNot sampledNot sampledNot sampledNot sampled
SydneyNot sampledNot sampledNot sampledNot sampled
Los AngelesNot sampledNot sampledNot sampledNot sampled
Sampling method: use a home broadband connection during the evening peak in China Standard Time. Send 100 ICMP requests to each destination, calculate the median round-trip time for successful responses, and record packet loss separately. This table is awaiting samples; it is not a completed measurement report. Any future results are for comparison only and do not guarantee latency.

Test from your local machine, not from the remote one

On macOS or Linux, run the command below locally. On Windows, use ping -n 100 with the target IP address. Record your provider, time of day, successful response count, and raw output. Keep the network and test conditions consistent when comparing results.

ping -c 100 "$MAC_IP"

Check jitter and packet loss as well as the median

The average reported by ping isn’t the median; calculate the median from the individual response times. Persistent packet loss or occasional high latency can make VNC feel sluggish, even when the median is low. If ICMP is filtered, SSH or VNC may still work—check the actual connection ports.

Finally, test the desktop with the same resolution, colour depth, and sequence of actions: type a sentence, drag a window, and see whether the screen refreshes smoothly.

Change one setting at a time

Save desktop bandwidth for the details that matter

Start with low-bandwidth settings to establish a baseline, then increase image quality one step at a time. After each change, repeat the same typing, scrolling, and window-dragging tests. Changing four settings at once makes it hard to tell what helped.

  1. 01

    Lower the colour depth

    If your client allows it, start with 16-bit colour or a lower image-quality setting to reduce the amount of data sent with each refresh. Restore higher quality when inspecting designs, colours, or screenshots; low-colour images aren’t suitable for colour review.

  2. 02

    Turn off animated wallpapers

    Switch to a static wallpaper and stop any unrelated video or continuous animation. A changing background uses bandwidth to refresh pixels that aren’t relevant to your current task. When checking simulator animations, keep only the windows you need visible.

  3. 03

    Limit the resolution

    Start at 1440 × 900 and increase it once you can comfortably see your editor and test window. Don’t raise the remote desktop resolution just because your local monitor supports a higher one; more pixels take more bandwidth to transfer and more resources to decode.

  4. 04

    Use the command line on weak networks

    Use SSH for builds, dependency installation, and log checks. Open VNC only when you need the interface. Transfer build artefacts and logs separately to avoid competing with desktop refreshes for upload bandwidth.

Tighten access after you connect

Keep a way back in before changing authentication

A dedicated physical Mac means you manage its environment; it doesn’t make a public network connection secure by default. Before changing authentication or firewall settings, keep one working session open and test the new settings in a second session.

Change the initial password

Replace the initial password as soon as possible after delivery. Choose a long, unique password that you don’t reuse for code hosting or email. Store credentials only in a trusted password manager—not in build logs or repositories.

Verify: Open a new session with the new credentials. Close the old session only after it works.

Use SSH key authentication

Install your public key and verify that you can connect with the private key before changing SSH authentication settings. Use a separate key for automation and grant only the access it needs. Revoke the relevant public key promptly if someone leaves your team or a key is exposed.

Verify: Connect from a second terminal with the intended private key, without relying on the existing session.

Open only the ports you need

Keep only the access points required for your work, and restrict source IPs where possible. Use a protected connection method for remote desktop access. Check SSH and VNC rules separately; don’t leave all protections disabled after troubleshooting.

Verify: Required ports are reachable and unnecessary access points remain closed.

Lock the desktop when you step away

Lock the screen and disconnect your client when you finish debugging. Remove any sensitive files downloaded temporarily. Don’t share private keys with your team; manage build keys and certificates through your team’s established process.

Verify: Reconnecting to the desktop requires authentication, and logs and screenshots contain no secrets.

Troubleshoot each step of the connection

Can’t connect? Don’t reinstall macOS just yet.

First determine whether the issue is a timeout, a refused connection, or an authentication failure. Check one layer at a time and keep the original error. Repeatedly changing passwords, ports, and firewall settings can erase clues about the original problem.

  1. 01

    Check the IP address and instance

    Reopen the machine details in the portal and confirm that the instance has been delivered and the address belongs to the current machine. Don’t use an old note, screenshot, or another machine’s address, and don’t enter the example variable names directly into your client.

  2. 02

    Check the protocol and port

    Use the SSH port in your SSH client and the desktop port in your VNC client. For a timeout, check the network and access rules first; for a refused connection, check the port and whether the service is listening. A successful ping doesn’t mean an application port is reachable.

  3. 03

    Check the username and credentials

    If authentication fails, check the username, key file, and authentication method selected in the client. Look for extra spaces introduced when copying, and make sure you’re using the current instance’s credentials. Verify any host-key warning rather than bypassing it.

  4. 04

    Check local network policies

    Check your local firewall, proxy, corporate network egress rules, and client permissions. If permitted, test from another network to see whether the issue changes with the route. Don’t permanently disable security software just to get one connection working.

Still stuck? Send us a reproducible support ticket

Include the instance ID, connection protocol, destination port, exact error message, time and time zone, and the steps you’ve already tried. “SSH works but VNC doesn’t” is more useful than “can’t connect”. Remove passwords, private keys, tokens, and other sensitive information from screenshots and logs first.

For an issue with a machine you’ve purchased, submit a ticket through the portal so we can associate it with your instance. For pre-sales questions about network routes or client compatibility, email support@metalvnc.com.

Sign in to submit a ticket More help
You’re ready to connect

Choose the closest location and get started

Compare the memory and storage of the two M4 options, then choose a location and billing period. Test SSH and desktop performance on your own network before scheduling ongoing builds. Availability is shown in real time in the portal.

Rent a cloud Mac Compare Macs and billing periods