Install CollaboKeys: Download DMG or Build from Source

CollaboKeys runs on macOS only on the host side — the key-emulation layer depends on the CoreGraphics framework, which is exclusive to Apple platforms. Players connect through any modern browser, so they have nothing to install. Getting the host app up and running typically takes under two minutes whether you prefer downloading a prebuilt release or compiling from source.

Download Release
Build from Source

The fastest way to get started is to download the prebuilt .dmg from GitHub Releases.

Download the DMG

Go to https://github.com/tinkerer9/CollaboKeys/releases/latest and download the .dmg file listed under Assets.

Install the app

Open the downloaded disk image. Drag the CollaboKeys icon into your Applications folder, then eject the disk image.

Launch CollaboKeys

Open Finder → Applications and double-click CollaboKeys to launch it.

macOS may show: “CollaboKeys is damaged and can’t be opened.”This is a Gatekeeper quarantine warning. CollaboKeys is not signed or notarized through Apple’s Developer Program, so macOS flags it with a quarantine attribute when it is downloaded from the internet. To remove the attribute and allow the app to launch, open Terminal and run:

xattr -dr com.apple.quarantine /Applications/CollaboKeys.app

After running that command, try launching CollaboKeys again. This is a standard one-time fix for open-source macOS apps that are not distributed through the Mac App Store.

Building from source lets you run the latest code directly and is the right choice if you want to modify CollaboKeys or skip the DMG entirely.Prerequisites: Node.js must be installed on your Mac.

Clone the repository

git clone https://github.com/tinkerer9/CollaboKeys.git

Install dependencies

cd CollaboKeys && npm install

This installs all runtime and development dependencies declared in package.json, including Socket.IO, Winston, Electron, and electron-builder.

Compile the C keyboard helper

npm run compile

This runs the following command under the hood, building a universal binary (arm64 + x86_64) that uses the macOS ApplicationServices framework to emulate keypresses:

clang src/emulate/helper.c -framework ApplicationServices \
  -arch arm64 -arch x86_64 -O3 -o src/emulate/helper

The output binary is written to src/emulate/helper. You must compile it before starting the app — it is not included in the repository.

Start the app

npm start

This launches CollaboKeys as a full Electron window. The admin dashboard opens automatically in the app once the server is ready.

Other run modes

Two additional npm scripts are available once the project is set up:

Script	Command	Description
Package	`npm run build`	Compiles the C helper, then packages the app into the `dist/` folder as a distributable `.dmg` using electron-builder.
Headless test	`npm test`	Runs `node src/server.js` directly in the terminal, starting the server without any Electron window. Useful for headless testing or running CollaboKeys on a machine without a display.

Accessibility permission

CollaboKeys requires macOS Accessibility permission to emulate keypresses through the CoreGraphics framework. Without it, the app can receive key events from players but cannot inject them into the active application on the host machine.

Granting Accessibility access:

On first launch, macOS will display a system prompt asking for Accessibility access. Click Open System Settings and enable the toggle next to CollaboKeys under Privacy & Security → Accessibility.
If the automatic prompt does not appear, open System Settings → Privacy & Security → Accessibility manually, click the + button, and add CollaboKeys from your Applications folder.

You only need to grant this permission once. macOS remembers the setting across relaunches.

Get Started

Playing

Administration

Configuration

Install CollaboKeys: Download DMG or Build from Source

Accessibility permission

Build docs developers (and LLMs) love

Get Started

Playing

Administration

Configuration

Documentation Index

​Accessibility permission

Build docs developers (and LLMs) love

Accessibility permission