How to connect to a macOS container via VNC

Overview

When troubleshooting macOS builds, sometimes it can be useful to find out what's happening on screen in the macOS GUI. This can be done by ensuring that VNC is enabled in the host OS, and setting up the credentials with which to connect to the host.

Note: It is not possible to know the password for the default user. As such this method creates a new user from whom you can VNC into the session and run any commands from there.

To connect to a macOS container using the macOS Orb:

• Set up your desired VNC password in an environment variable or context variable named MAC_ORB_VNC_PASSWORD
• Implement the macOS orb v. >2.3.0 into your project's config.yml:

orbs:
  mac: circleci/macos@2.3.0

jobs:
  build:
    steps:
      - mac/enable-vnc

• Install a VNC viewer on your local machine:
  • macOS users can use the Screen Sharing app
  • Linux and Windows users can download and install TightVNC or RealVNC Viewer
• Re-run the Job you wish to VNC into with SSH
  • More details about SSH Access Jobs can be found in our documentation
• Configure SSH port forwarding on your local machine:
  • ssh -p 54782 <mac container ip> -L5901:localhost:5900 -N
• Connect to the VNC session from your VNC client:
  • Connect to localhost:5901
  • Use credentials vncuser and the password you set in MAC_ORB_VNC_PASSWORD

Tip: You can find more information on the macOS Orb documentation page.

Additional Details:

• It is a requirement to re-run jobs with SSH to connect to a macOS environment using VNC

Additional Resources

• Adjust screen resolution on macOS executor
• macOS Build Times Out With "Too long with no output"