Start with SSH to verify command-line access, then connect to the desktop over VNC. To limit exposure to the public internet, route VNC through an SSH tunnel. Your rental is a dedicated physical Mac, not a virtual machine. Use the address, port, and account details provided in your portal.
Don’t have a machine yet? Choose a model and location first. Already have an order? Sign in to your portal, find the instance’s connection details, and start with step one below.
Copy these four details from your portal before connecting. Never share your password or private key in a support ticket.
SSH provides an encrypted command-line connection. Run it in Terminal on macOS or Linux, or in PowerShell on Windows. Replace the example address, port, and username with the values provided in your portal.
ssh-ed25519 to the remote account’s ~/.ssh/authorized_keys.ssh -p <SSH-port> <username>@<host-address>
ssh-keygen -t ed25519 -C "cloud-mac"
cat ~/.ssh/id_ed25519.pub
ssh -i ~/.ssh/id_ed25519 \
-p <SSH-port> <username>@<host-address>If you already have a key, check the filename first so you don’t overwrite an existing private key. Paste the entire public key as a single line. Set the permissions for remote ~/.ssh and authorized_keys to 700 and 600, respectively.
VNC lets you view and control your Mac’s desktop from your computer. Check the desktop address, port, and authentication method provided in your portal; they may differ from your SSH details.
Open Screen Sharing and enter the VNC address and port provided with your instance. If you’ve set up the SSH tunnel below, connect to the local address and port instead. Authenticate with the details provided—not your SSH private key.
Ideal for working with Xcode, Simulator, and system settings.
Enter the host, port, and authentication details provided in your VNC client. If it requires a single address, use the “host:port” format specified by the client. For an SSH tunnel, connect to the local loopback address instead.
Select VNC as the protocol. The desktop port is not the SSH port.
Lower the image quality from its highest setting and reduce the frame rate requested by the client. Start with one display and a suitable desktop resolution to check that the connection is stable. If keyboard input is responsive but the display isn’t, check the network route to your location before reinstalling your development environment.
An SSH tunnel securely forwards a local port on your computer to the remote desktop port. Your client connects only to your own machine, so there’s no need to expose VNC to the public internet for convenience. Check that your connection details support this setup before running the command.
5901 is an available local port you choose; it doesn’t mean the server always uses that port.-N creates the tunnel without running a remote command.127.0.0.1:5901. When you’re done, quit the client and then close the terminal running the tunnel.ssh -N \
-L 127.0.0.1:5901:127.0.0.1:<remote-VNC-port> \
-p <SSH-port> \
<username>@<host-address>If local port 5901 is already in use, change only the first port in -L and use that same new port in your VNC client. Don’t change the remote port to resolve a local port conflict.
A self-hosted runner executes CI jobs on a machine you manage. First, connect over SSH and make sure the Xcode command-line tools are available. Then create registration credentials in your CI project settings. Never add a one-time token to your repository or build logs.
In your project’s runner settings, choose a macOS runner and follow the current installation and configuration commands shown there to register your cloud Mac. Use labels that identify the model, location, and purpose, such as macos, m4, and ios-build. Make sure your workflow’s runs-on value matches the labels you set.
After registration, run a small test job that only executes xcodebuild -version before moving on to production builds.
Get the current registration instructions for your project, install a matching runner version on your cloud Mac, and choose the shell executor if your project requires it. Give the runner clear location and build labels. Check that protected jobs can run on this runner before submitting a test pipeline.
Verify that jobs can access Xcode, signing assets, and project dependencies before increasing concurrency.
Use the runner’s official service installation method to register it as a macOS background service, and specify which account it should run under. After restarting, check the service status and run a test job. A successful build in an interactive terminal doesn’t guarantee that a background service can access the same environment variables or keychain. Before your rental ends, revoke the registration token and back up any artifacts you need to keep.
There are four available locations: Singapore, Tokyo, Seoul, and Hong Kong. Choose the one closest to the people who will be using the machine, then test SSH response times and desktop responsiveness from your actual work network. Cross-border routes, packet loss, and your local network can all affect performance, so location names alone don’t tell the whole story.
| Location | Teams best served | What to check first |
|---|---|---|
| Singapore | Development and build teams in Southeast Asia | Actual round-trip latency from your office network |
| Japan (Tokyo) | Development teams in Japan and nearby regions | Desktop responsiveness and build artifact transfers |
| South Korea (Seoul) | Development teams in South Korea and Northeast Asia | Packet loss during peak hours |
| Hong Kong | Teams collaborating across South China and Southeast Asia | Each team member’s network route |
Both Mac tiers are available in all four locations. Check your portal for current availability when placing an order. If your team is spread across multiple locations, choose based on where the people using the desktop are based, then consider the source and artifact transfer routes for CI jobs.
Thunderbolt 5 linking is useful for build tasks that coordinate multiple machines in the same location or workflows that frequently move large files between them. The add-on is billed per machine: $1/day. Choose it based on your transfer and concurrency needs—it isn’t required for VNC or CI on a single Mac.
For example, assign multiple app targets, test shards, or builds for different versions to separate runners. Give each machine distinct labels so jobs don’t end up on a machine without the required tools.
Measure build time on one machine before estimating the gains from parallel runs.
If your builds spend most of their time waiting for signing, dependency downloads, or external services, a linked setup may not address the bottleneck. List the files to transfer, how often you’ll transfer them, and how many machines you need, then check the add-on in your order configuration.
Linking machines locally won’t handle collaboration across different locations on its own.
First check the instance status, address, and ports in your portal. Then work out whether the issue is with SSH, VNC, or your local network. Don’t repeatedly reset the environment before backing up your build artifacts.
First check that SSH still works, then disconnect and reconnect the desktop session. Verify the VNC authentication details, that the tunnel is still running, and that the client is using either the local forwarded port or the direct port provided with your instance. If SSH works but multiple clients continue to show a black screen, open a support ticket in your portal and include the instance ID, when the issue started, and a screenshot.
Turn off fixed scaling in the client first, then check the macOS display settings. Test the remote desktop with one display at a common resolution. Reconnect after making changes to determine whether the issue comes from the display settings on the Mac or scaling in the client.
Check that the keyboard layouts on your local and remote machines match, especially for punctuation and the Option and Command keys. Review modifier-key mappings in the client settings. Test a few characters in a text editor before entering commands or changing signing settings.
Reconnect over SSH first. If you use a tunnel, run the forwarding command again, then connect to the local VNC port. Where possible, run builds on a background runner rather than relying on a desktop terminal that must stay connected. If neither SSH nor VNC reconnects, open a support ticket in your portal with your order number, location ID, and a screenshot of the error.
Start with a small SSH task. Once the desktop and CI meet your needs, decide whether to extend your rental or add another machine. Need help with an existing instance? Sign in to your portal and open a support ticket.