Get a MacOS desktop over VNC, for free, in around 5 minutes
Shell that configure a MacOS VNC server that can run in a Github Actions VM and can be accessed through a tcp tunnel.
NOTE: This repo is based in fastmac and fastmac-VNCgui.
This repo includes a shell and a pipeline for Github Actions that
- enables the built in MacOS VNC server, doing a hacky trick to set a VNC password and a new admin user
- installs
ngrokand uses it to set up a tcp tunnel for VNC/Apple Screen Sharing. - runs tmate to setup a Web Shell and a SSH connection
You must clone this repo, configure some secrets in the cloned repo and execute one of the Github Actions pipelines.
This repository has been configured as a template. You can create a new repository using this link
- Type
debug-on-macunder "repository name" - and then click "Create repository from template".
To get a running MacOS desktop, you must configure three secrets for the Github Actions:
NGROK_AUTH_TOKENwith your auth key from https://dashboard.ngrok.com/authVNC_USER_PASSWORDwith the desired password for the "VNC User" (vncuser) accountVNC_PASSWORDfor the VNC-only password
After configuring the secrets, you can start a MacOS desktop by running the "macos-with-vnc" Github Actions
- Go to the macos-with-vnc pipeline
- Click the "Run workflow" dropdown on the right, and
- Click the green "Run workflow" button that appears.
Once the pipeline is started and you're in the status, you can view the 'you can VNC to...' section in the workflow log for your ngrok tunnel VNC address.
If you are using Apple Screen Sharing or RealVNC Viewer
- use the ngrok tunnel VNC address as the VNC ip address
- use the system username and password ("VNC User"/your set password)
If you are using any other VNC client
- use the ngrok tunnel VNC address as the VNC ip address
- use the VNC-only password, configured above as a secret.
NOTE: If you start a MacOS desktop, you can access the desktop using a SSH shell. You may follow the steps described bellow to connect to the MacOs Shell.
After configuring the secrets, you can start a MacOS shell by running the "macos-with-ssh" Github Actions
- Go to the macos-with-ssh pipeline
- Click the "Run workflow" dropdown on the right, and
- Click the green "Run workflow" button that appears.
Once the pipeline is started and you're in the status, you can view the "Setup tmate session" section. There, once the tmate software is installed, it will repeatedly print lines like this:
WebURL: https://tmate.io/t/rXbusP3qkYsfALDSLMQZVwG3d
SSH: ssh rXbusP3qkYsfALDSLMQZVwG3d@sfo2.tmate.io
Copy and paste the ssh line (e.g ssh rXbusP3qkYsfALDSLMQZVwG3d@sfo2.tmate.io in this case) into your terminal (Windows users: I strongly recommend you use WSL if possible) and press Enter.
Your session will run for up to six hours. When you're finished, you should close it, since otherwise you're taking up a whole computer that someone else could otherwise be using!
To close the session, click the red "Cancel workflow" on the right-hand side of the Actions screen (the one you copied the ssh line from).
Please check the GitHub Actions Terms of Service. Note that your repo needs to be public, otherwise you have a strict monthly limit on how many minutes you can use. Note also that according to the TOS the repo that contains these files needs to be the same one where you're developing the project that you're using it for, and specifically that you are using it for the "production, testing, deployment, or publication of [that] software project".
This pipeline is a thin wrapper around tmate, so all the features of tmate are available. tmate itself is based on tmux, so you have all that functionality too. In practice, that means other people can connect to the same ssh session, and you'll all be sharing the same screen! This can be very handy for debugging and support. The integration with Github Actions is provided by action-tmate.