From credentials to a working setup

Three ways to connect to your M4

Use SSH for the command line, a remote desktop for interactive work, and a CI runner for automated builds. All three connect to the same dedicated physical node—not separate environments.

Rent a Cloud Mac View credentials in console

Already renting? Open the instance details for your order in the console to find the host address, SSH port, username, and setup instructions. Replace the host variables in this guide with the actual values for your instance.

SSHVerify the host, sync files, and run builds

Remote desktopUse Xcode, the Simulator, and the macOS interface

CI runnerRun project jobs on your own physical node

Start with a connection you can verify

SSH: Generate a key and add a host alias

Connect to the command line first, then set up the desktop and pipeline. SSH is also the quickest way to check whether the node is reachable and troubleshoot authentication.

01
Generate a key locally
Run this on your own computer, not on the cloud node. Protect the key with a passphrase. If you already have a dedicated key, you can reuse it; don't overwrite a file that's still in use. Keep the private key on your computer. Only the public key ending in .pub is provided to the node.
```
ssh-keygen -t ed25519 -f ~/.ssh/xcnode_ed25519 -C "xcnode-workstation"
ssh-add ~/.ssh/xcnode_ed25519
```
If ssh-add says it can't connect to the authentication agent, first make sure your local SSH agent is running. Your key passphrase is different from your remote account password.
02
Install your public key and verify the host
Set the three variables according to your instance instructions. Use ssh-copy-idonly if the setup instructions allow password authentication for the initial setup. If your public key is already registered, test the connection directly. On your first connection, verify the host fingerprint—don't accept an unknown host just because you're prompted to confirm it.
```
read -r -p "Host: " NODE_HOST
read -r -p "SSH port: " NODE_PORT
read -r -p "User: " NODE_USER
ssh-copy-id -i ~/.ssh/xcnode_ed25519.pub -p "$NODE_PORT" "$NODE_USER@$NODE_HOST"
ssh -i ~/.ssh/xcnode_ed25519 -p "$NODE_PORT" "$NODE_USER@$NODE_HOST"
```
These variable prompts are for Bash. On macOS, you can start Bash from zsh by running bash first. If you can't install the public key initially, use the credential management option in the console or open a support ticket. Don't keep retrying passwords.
03
Save an alias and check your environment
Add an alias to your local ~/.ssh/config . Replace the angle-bracket placeholders below with your instance values, and remove the brackets. Windows OpenSSH also reads .ssh/configin your user directory.
```
Host xcnode-work
  HostName <INSTANCE_HOST>
  Port <SSH_PORT>
  User <INSTANCE_USER>
  IdentityFile ~/.ssh/xcnode_ed25519
  IdentitiesOnly yes
  ServerAliveInterval 30
  ServerAliveCountMax 3
```
```
ssh xcnode-work
uname -m
sysctl -n machdep.cpu.brand_string
xcode-select -p
xcodebuild -version
```
uname -m should return arm64. The chip name should match the model in your order. Check the Xcode version against what's actually installed on the node. Keeping a connection alive won't automatically resume a task; use a runner or persistent session manager for long builds.

Three client platforms, three things to check

First, make sure your local machine can run ssh -V. Missing a helper command doesn't mean the node doesn't support SSH.

Preparing your local client and installing a public key
Local system	SSH client	Public key setup	Notes
macOS	OpenSSH included in Terminal	`ssh-copy-id` Usually needs to be installed separately. You can also register your public key as described in your setup instructions.	The default shell is usually zsh. Don't copy Bash-specific prompt syntax directly.
Windows	OpenSSH Client in PowerShell	Use it in WSL with `ssh-copy-id`, or register your public key in the console.	PowerShell and WSL use separate user directories and key files.
Linux	OpenSSH client package for your distribution	Usually includes `ssh-copy-id`. If not, install the client tools first.	Set private key permissions to `600`, and`~/.ssh` directory permissions to `700`.

When you need a desktop

Remote desktop: Use an SSH tunnel

Once SSH works, check the Screen Sharing service and graphical session. A reachable port doesn't mean the desktop is ready.

macOS Screen Sharing

On a local Mac, you can use the built-in Screen Sharing app. VNC commonly uses TCP port 5900. Check your instance instructions for the actual port, authentication method, and whether the service is enabled.

Once you've confirmed the remote port is 5900, create a tunnel in your local terminal and leave it running. This example uses local port 15900 to avoid conflicts with services on your computer.

ssh -N -L 127.0.0.1:15900:127.0.0.1:5900 \
  -o ExitOnForwardFailure=yes xcnode-work

Then open the client in another terminal:

open "vnc://127.0.0.1:15900"

The tunnel listens only on your local loopback address

VNC clients for Windows and Linux

Choose a VNC client that supports your instance's authentication method, such as TigerVNC. Set up the same SSH tunnel, then enter 127.0.0.1as the client address and 15900as the port.

Port entry varies by client: some have a separate port field, while others use a double colon to specify the full port. Follow your client's instructions, and don't mistake the port for a display number.

macOS Screen Sharing authentication isn't always compatible with generic VNC clients. If authentication fails, check the client's capabilities and your setup instructions first. Don't weaken node security just to accommodate a client.

Manage desktop credentials separately from SSH keys

Start with lower image quality for smoother interaction

For your first connection, choose automatic or lower image quality and use just one display. Avoid transferring large files while streaming full-screen motion. Once text is clear and clicks respond reliably, gradually increase the resolution and color quality. Fast SSH file transfers don't mean low latency for the remote desktop.

If the screen is black, check in this order: is the tunnel still running, is the target port correct, is Screen Sharing enabled, and is a graphical session available on the remote Mac? If sessions conflict, coordinate with your team rather than forcibly logging out someone whose build is running.

Send jobs straight to the node

CI setup: Register once, then verify startup

The runner executes on your Cloud Mac, not your local computer. Test your toolchain with an interactive job first, then run it as a service.

GitHub Actions self-hosted runner

Open your project or organization runner settings and select macOS ARM64. Follow the current page instructions to download and verify the runner. Get the registration URL and short-lived token from that settings page.

cd ~/actions-runner
read -r -p "Registration URL: " RUNNER_URL
read -r -s -p "Registration token: " RUNNER_TOKEN
printf '\n'
./config.sh --url "$RUNNER_URL" --token "$RUNNER_TOKEN" \
  --name xcnode-work --labels xcnode,arm64
unset RUNNER_TOKEN
./run.sh

Run these prompts in Bash. Submit a test job and confirm the runner comes online and completes a build. Then stop the foreground process and install the service:

./svc.sh install
./svc.sh start
./svc.sh status

Use explicit labels in your workflow to avoid sending jobs to a machine with a different architecture:

runs-on: [self-hosted, macOS, ARM64, xcnode]
steps:
  - run: xcodebuild -version

A registration token isn't a long-term project secret. Don't put it in your repository, build output, or ticket attachments.

GitLab Runner

Create a runner in your project or group and get its runner authentication token according to the current platform instructions. Install the macOS ARM64 version, then register it in a terminal within the target run user's graphical session. Don't run project builds as root.

gitlab-runner register

Enter the instance URL and authentication token when prompted, then choose the shell executor. Set the runner's xcnode and arm64 tags, and restrict it to trusted projects.

gitlab-runner install
gitlab-runner start
gitlab-runner status

Start with a minimal test job to check the environment, then add signing and archiving:

build-check:
  tags: [xcnode, arm64]
  script:
    - uname -m
    - xcode-select -p
    - xcodebuild -version

The Shell executor can access files available to its run user. A dedicated machine doesn't isolate untrusted jobs running under the same account.

Verify startup and interactive access separately

On macOS, user-level services are usually managed by launchd and may depend on a user session. After installing the service, check its process, logs, and queue status. Test recovery after a restart at a time your team approves. Jobs that need a Simulator or graphical interaction also require a suitable login session; an online runner alone isn't enough.

Start with one job, record the project's actual peak memory use, then increase concurrency. Cache by project and Xcode version, and archive build artifacts separately. If you use signing credentials in the system Keychain, verify that the service user can access them. A successful build in Terminal doesn't guarantee that a background build will work.

Choose a location based on your network

Four locations: test your usual work network first

Singapore, Tokyo, Seoul, and Hong Kong each offer two machine tiers. Availability is shown in real time in the console. Distance is only a starting point—carrier routing and your team's working hours matter too.

Singapore

A good first option to test for teams in Southeast Asia. Check desktop responsiveness on your actual office network, then test your code checkout and artifact upload paths.

sg · UTC+8

Tokyo

A good first option to test for teams in Japan and East Asia. A nearby time zone doesn't guarantee a faster connection, so compare performance at peak and off-peak times.

jp · UTC+9

Seoul

A good first option to test for teams in South Korea and Northeast Asia. For a persistent runner, check that access to your code repositories and dependency sources is reliable.

kr · UTC+9

Hong Kong

A good first option to test for teams in South China and Southeast Asia. If you share a desktop across time zones, agree in advance on when to use and sign out of the graphical session.

hk · UTC+8

Track three things: round-trip time, variation, and real tasks

Run checks against the actual host address assigned to your instance. Testing the website domain won't tell you how the node performs. Run the commands below in a local Bash terminal after setting the node variables.

ping -c 20 "$NODE_HOST"
ssh -p "$NODE_PORT" "$NODE_USER@$NODE_HOST" 'uptime'

In Windows PowerShell, run ping -n 20 <INSTANCE_HOST>. Note packet loss and the range of round-trip times, then test an actual Git checkout or artifact transfer. ICMP may be filtered by network policy. If ping gets no response, test the actual SSH port separately.

Repeat tests on your team's usual network and during your normal working hours. We don't promise a uniform latency; results reflect only that network path at that time. If you haven't rented a node yet, contact us by email to ask how to test. Don't guess the node address.

Put the concepts side by side

Eight connection terms, explained

Separate resource boundaries, connection protocols, and job scheduling to avoid mixing up different layers when troubleshooting.

Physical node: A physical Apple Silicon machine running macOS. Your order assigns an entire device, not a virtual machine on a shared host.
Dedicated: During the rental period, the physical machine is assigned to one tenant. Its CPU, GPU, and unified memory aren't shared with other tenants.
VNC: A protocol for transmitting a remote screen and keyboard and mouse input. Check its service status, port, and authentication separately.
Screen Sharing: The macOS capability and client for accessing a remote graphical session. It doesn't replace SSH for command-line access.
SSH key: An identity credential made up of a public and private key. Register the public key with the node; keep the private key on a secured client.
self-hosted runner: An agent that runs CI jobs on your own node, using the node's toolchain, permissions, and cache.
Thunderbolt 5 interconnect: An optional node connection selected per machine. It doesn't automatically combine multiple devices into one shared-memory system; software must still support distributed workloads.
Unified memory: CPU and GPU share the same memory pool on Apple Silicon. Budget memory usage across builds, simulators, and model workloads.

Connect securely—and stay in control

Verify your key before tightening access

Don't change authentication until you've verified your only connection. Keep your current session open and use a second terminal to confirm the new key works before changing node settings.

Disable password authentication

Check the sshd configuration and included files for your macOS version. Enable public key authentication and disable password and keyboard-interactive authentication. Don't change just one setting that another file might override.

PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no

Before applying the configuration, run sudo /usr/sbin/sshd -t to check the syntax, then apply it according to your instance instructions.

Open only the ports you need

Connect to SSH on the port provided with your instance. For remote desktop access, use a local tunnel whenever possible instead of exposing port 5900 to the public internet. Shut down temporary test services when you're done, and check both listening addresses and firewall rules.

lsof -nP -iTCP -sTCP:LISTEN

Runners usually connect out to the CI service, so don't open extra inbound management ports.

Manage credentials by person and task

Give each team member a separate public key and remove their authorization when they leave. Allow the runner to accept jobs only from trusted repositories. Store project secrets in protected CI variables, not in scripts or project files.

If the host fingerprint changes, first confirm whether the instance was reinstalled. Don't simply delete the local record and reconnect.

Attach only redacted logs, your order number, and the steps that failed to a support ticket. Never send private keys, passwords, or registration tokens.

Review isolation and data handling View the connection troubleshooting guide

Turn your local workflow into a repeatable remote workstation

Choose a model and rental term, then get your instance credentials. Start by verifying SSH, then connect the remote desktop and build queue step by step. If an existing instance is blocked, submit a redacted troubleshooting report in the console.

Rent a Cloud Mac Log in to the console to open a support ticket