# macOS server troubleshooting: access, sleep, keychain and Xcode

> Fix common problems on a remote Mac: no desktop connection, a Mac that sleeps, codesign errSecInternalComponent over SSH, missing simulators, full disk.

Difficulty: Intermediate

A remote Mac is a normal Mac with a long cable. When something goes wrong, the cause is usually one of a handful of things. Find your symptom below.

## Before you start

- Know your Mac's connection methods: **HyperDC Web Console** for every HyperDC Mac; **VMRC** for Intel macOS VPS and VDS; **Apple Remote Desktop** and **HyperDC Remote Connect** for Apple Silicon macOS VPS and Mac dedicated servers. See [first steps on a macOS server](/guides/macos-server-first-steps).
- Check **Support › Network Status** in the client area for maintenance or incidents at your location.

## I cannot reach the desktop

**Try the HyperDC Web Console first.** Open your service in the client area and start the Web Console.

- **The Web Console shows the desktop:** the Mac runs. The problem is your other method or the network between you and the Mac. For Apple Remote Desktop, check that ports `3283` and `5900` are not blocked on your side and that **Remote Management** is on; see [Apple Remote Desktop](/guides/connect-to-mac-apple-remote-desktop).
- **The Web Console shows the login window:** the Mac restarted. Sign in; apps that need a session, such as Docker Desktop, start again after sign-in.
- **The Web Console shows a black screen:** the display is asleep. Move the mouse or press a key in the console window. If it stays black, disconnect and connect again.
- **The Web Console does not connect either:** open a ticket with your service name and the time the problem started.

## The Mac goes to sleep

Builds stop and connections drop when the Mac sleeps. In Terminal:

```bash
pmset -g
sudo pmset -a sleep 0
```

On Mac dedicated servers, also check **System Settings › Energy**; see [set up a Mac dedicated server](/guides/mac-dedicated-server-setup).

## codesign fails over SSH or in CI

**Symptom:** `codesign` or `xcodebuild archive` works in the desktop but fails over SSH or in a CI job with `errSecInternalComponent`.

**Cause:** the login keychain is locked in that session. macOS unlocks it at a desktop sign-in, not for SSH.

**Fix:** unlock the keychain in the **same** shell session or command chain as the signing step:

```bash
security unlock-keychain ~/Library/Keychains/login.keychain-db && xcodebuild -scheme MyApp archive
```

In CI, keep the keychain password in the CI system's secret store and pass it to `security unlock-keychain -p` at runtime; never write it into scripts. If signing still fails, look for duplicate or expired identities:

```bash
security find-identity -v -p codesigning
```

## A simulator runtime is missing

**Symptom:** Xcode or `xcodebuild test` reports that no matching destination or simulator runtime is available.

**Fix:** list what is installed, then download the platform with Xcode's command-line tool:

```bash
xcrun simctl list runtimes
xcodebuild -downloadPlatform iOS
```

Runtimes take several gigabytes each; check `df -h /` first.

## Xcode will not install or open

The macOS version is too old for that Xcode release. Check Apple's Xcode system requirements, then update macOS or choose an Xcode that supports your version; see [macOS VPS and VDS](/guides/macos-vps) for how Xcode releases and macOS versions relate.

## The disk is full

```bash
df -h /
xcrun simctl delete unavailable
du -sh ~/Library/Developer/Xcode/DerivedData
```

Delete old DerivedData folders, archives you have uploaded and Xcode versions you no longer need. You can add disk space in the order form or move to a larger plan.

## SSH: Connection refused

**Remote Login** is off. Turn it on in **System Settings › General › Sharing** through the Web Console, then connect again.

## macOS updates fail or stop halfway

Check free space and the update list:

```bash
softwareupdate --list
```

Install with `sudo softwareupdate --install --all --restart` when no jobs are running. On a virtual Mac, ask us before a **major** macOS upgrade, so we can confirm the new version is supported for your plan.

## Next steps

- Prepare a build machine: [macOS server for iOS CI](/guides/macos-server-for-ios-ci).
- Mac dedicated servers: [set up a Mac dedicated server](/guides/mac-dedicated-server-setup).

## Frequently asked questions

### Which connection should I try when one fails?

The HyperDC Web Console in your browser works for every HyperDC Mac. If it shows the desktop, the Mac is fine and the problem is the other connection method or the network in between.

### Why does codesign work in the desktop but not over SSH?

macOS unlocks your login keychain when you sign in at the desktop. An SSH session does not, so codesign cannot use the signing key until you unlock the keychain in that session.

### Can I sign in with my Apple Account on an Apple Silicon macOS VPS?

On Apple silicon, macOS 15 and later support signing in with an Apple Account inside virtual machines created with macOS 15 or later. Tell us if your workflow depends on it, so we can confirm the setup.

### How do I free disk space quickly?

Delete unavailable simulators with xcrun simctl delete unavailable, old DerivedData folders and Xcode versions you no longer use. Check the result with df -h /.

---

Source: <https://hyperdc.com/guides/products/macos-server-troubleshooting>\
Updated: 2026-10-15