How to connect to a macOS container via VNC


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:

mac: circleci/macos@2.3.0

- 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
  • 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

Was this article helpful?
7 out of 18 found this helpful



Article is closed for comments.