Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tinkerer9/CollaboKeys/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart walks you through launching CollaboKeys on your Mac, inviting players on your local network, and playing your first collaborative keyboard game together — all in under five minutes.
Prerequisites:
  • CollaboKeys is installed on the host Mac (see Installation)
  • macOS Accessibility permission has been granted to CollaboKeys
  • All players have a modern web browser (no installation needed)
  • The host and all players are connected to the same local Wi-Fi network

​
Steps

1

Open CollaboKeys

Launch CollaboKeys from your Applications folder (or run npm start if you built from source).The app displays a brief splash screen while it starts, then automatically opens the admin panel in the app window. The server is now running and ready to accept player connections.
2

Find the server URL

In the admin panel, click the Show Link button (this runs the uri command internally). CollaboKeys will display the full URL players should visit — something like:
http://192.168.1.42:3000
This URL is your Mac’s local network IP address plus the port CollaboKeys is running on.
Players must be on the same local network as your Mac. The URL shown will not work over the internet or across different Wi-Fi networks.
3

Share the URL with players

Send the server URL to everyone who wants to play. You can share it via a group chat, show it on screen, or read it aloud. Players do not need to install anything.
4

Each player joins in their browser

Players open the URL in any web browser. They will be prompted to enter a username:
  • Minimum 3 characters, maximum 20 characters
  • Only alphanumeric characters (a–z, A–Z, 0–9)
After entering a valid username they click Continue and are placed directly into the session.
5

Open any keyboard-controlled game on the host Mac

On the host Mac, open the game you want to play — in a browser, as a desktop app, or anywhere else. Make sure the game window is in focus so that CollaboKeys’s emulated keypresses are delivered to it.
6

Players claim their keys

Players can now start pressing keys in their browser. The rules are simple:
  • The first time a player presses a key, that key is reserved for them exclusively.
  • No other player can use that key from that point on.
  • Each player’s reserved keys are shown on the right side of their screen.
  • Pressing a key that is already reserved by someone else has no effect.
Keypresses are transmitted in real time via Socket.IO and emulated natively on the host Mac using the ApplicationServices framework.
7

Collaborate to control the game

All players are now controlling the game together — each responsible for only the keys they’ve claimed. Coordinate, communicate, and cooperate (or descend into beautiful chaos) to play the game as a team.
A player can release all of their claimed keys at any time by refreshing the page in their browser. They’ll be taken back to the username screen and can rejoin fresh.

​
Try It: Play 2048 Together

2048 is a perfect beginner game for CollaboKeys. It uses only the four arrow keys, so each player can take exactly one direction. Try it with four players — one controls ←, one controls →, one controls ↑, and one controls ↓. Can you reach the 2048 tile while disagreeing about every move? For an extra challenge, don’t communicate with your teammates at all!

​
Stopping a Session

There are several ways to stop a CollaboKeys session:
  • Quit the app — two-finger-click the CollaboKeys icon in the Dock and select Quit. This shuts down the server and disconnects all players.
  • Admin panel stop button — in the admin panel, click the stop program button in the Controls section. This works from any device that has the admin page open, not just the host.
  • Console command — if you are running CollaboKeys from the terminal (npm start or npm test), type stop and press Enter.
  • Force Quit — if the app is unresponsive, press Command + Option + Escape, select CollaboKeys, and click Force Quit.

​
What’s Next

Gameplay & How It Works

Learn about key reservation, supported keys, and what makes a game compatible with CollaboKeys.

Admin Panel

Explore all the controls available in the admin panel, including player management and live logs.

Configuration File

Customize ports, player limits, key restrictions, passwords, and more via src/config.json.

Build docs developers (and LLMs) love

Get started for freeTalk to us