Mac

Owned by Luke Derrick
Last updated: Oct 10, 2024
3 min read

These are instructions on how to set up the Gumband OS Monitor on a mac host machine.

Setup

  • Download the Gumband OS Monitor zip file at the bottom of this page, and extract its contents. Copy its contents as root to /Library/LaunchDaemons. You must copy them as root so they are owned by the root user, which will allow the OS Monitor to reboot the computer:

    sudo cp ~/Downloads/gumband-os-monitor-macos-arm64/gumband-os-monitor-macos-arm64 /Library/LaunchDaemons sudo cp ~/Downloads/gumband-os-monitor-macos-arm64/launch-os-monitor.plist /Library/LaunchDaemons

  • Create an exhibit in the Gumband UI, and get an exhibit token and id.

  • Add a .env file to the /Library/LaunchDaemons directory and add the exhibit token and id from the previous step:

EXHIBIT_TOKEN=02b6903aece21b6sff520ac92dcba457 EXHIBIT_ID=1 # If the Gumband UI you're connecting to is not app.gumband.com, you'll # need to add two more environment variables here: # ENDPOINT=custom <----- indicates a custom IP. Should be set to the string, "custom" # CUSTOM_IP=other.gmbnd.com <----- defines an endpoint that isn't app.gumband.com

  • Give the /Library/LaunchDaemons/gumband-os-monitor-macos-arm64 file “Screen Recording” access under System Preferences → Security & Privacy → Privacy. This is so it has permission to take screenshots.

  • Load the plist file as the root user:

    sudo launchctl load -w /Library/LaunchDaemons/launch-os-monitor.plist

    Once you try to load the plist file, you’ll receive a warning that the gumband-os-monitor-macos-arm64 executable cannot be run, because it is from an unverified developer. You will need to make an exception to allow it to run. Go to System Preferences → Security & Privacy → General and select “Allow apps downloaded from: App Store and identified developers”, then click the “Open Anyway” button.

You should see the Gumband OS Monitor come online in the Gumband UI:

The Gumband OS Monitor showing as “Online” in the Gumband UI. Note the online icon boxed in red.

Testing

  • Check that the screenshot functionality is working. Click the "Take Screenshot" button on the "Control" tab in Gumband. It should upload one or more screenshots to the "Files" tab depending on how many monitors are connected to the computer.

  • Check that the reboot control is working. Click the "Reboot" button on the "Control” tab in Gumband. The host machine should reboot.

  • When the host machine boots up again, the OS Monitor should automatically launch and connect to Gumband.

Troubleshooting

Ensure that the plist file is located in /Library/LaunchDaemons. The daemon will not start automatically unless it is in this directory.

FireVault prevents the operating system from starting before a user logs in. To start the OS Monitor before login, you’ll need to disable FireVault.

Run sudo launchctl list | grep com.boot.osmonitor. This will list the daemon process if it exists.

  1. If the process does not exist, make sure you are loading the plist file as root (see instructions above).

  2. If the process exists and has a status of zero but without an ID, such as: - 0 com.boot.osmonitor, the OS Monitor is running but the exhibit credentials are probably incorrect. Double check that your .env file is correct

  3. If the process exists but has a status of 78, such as: - 78 com.boot.osmonitor, the OS Monitor has failed to run. The problem is likely that the plist file or the OS Monitor has an incorrect owner or has incorrect permissions. Run ls -al /Library/LaunchDaemons, and ensure that the owner of both files is root and in the wheel group and that the files have permissions to be executed.

This is because the OS Monitor needs “Screen Recording” permissions. See installation instructions above.

This is because the OS Monitor is not being run as the root user. Ensure that the plist and executable files are owned by root and that you load the plist with the sudo command. See installation instructions above.

Zip Download