This guide walks through a complete CollaboKeys session from scratch — from launching the app on the host machine to players pressing keys together in a real game. By the end you will have a working multiplayer keyboard session running on your local network.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.
Start CollaboKeys
Launch CollaboKeys from your Applications folder, or if you built from source, run:The Electron app opens and displays a brief splash screen while the server initialises. Once ready, the app navigates to the admin dashboard at:The server tries the following ports in order and uses the first one that is available: 3000, 8080, 8000, 5000, 2000, 4000, 6000, 7000, 9000. If all of those are occupied it falls back to a random port assigned by the operating system.
Find your server URL
In the admin dashboard, locate the Controls section and click the Show Link button. This runs the This is the address players will open in their browsers. Copy it or keep the admin page visible so you can share it in the next step.
uri command internally and displays your machine’s local IP address together with the active port — for example:Share the link with players
Send the URL you found in the previous step to everyone who wants to play. Any method works — a chat message, AirDrop, a shared note, or even reading it out loud. Players must be on the same local network as the host; the link will not be reachable from a different network.Players open the URL in any modern browser. No installation or account is required on their end.
Players enter a username
When a player opens the URL they see the CollaboKeys player page. They type a username and click Continue.Usernames must be 3–20 characters long and contain only alphanumeric characters (
a–z, A–Z, 0–9). The server enforces this and will display an error if the name is too short, too long, or contains invalid characters.Open your game
On the host machine, open the keyboard-controlled game or app you want to play. Because CollaboKeys injects keypresses into whichever application is currently in focus, make sure the game window is active and in the foreground before players start pressing keys.Any keyboard-driven game works as long as it does not require mouse input alongside keyboard input.
Start playing
Players can now press keys in their browser. Here is what happens under the hood:
- The browser captures
keydownandkeyupevents and sends them to the CollaboKeys server over a Socket.IO connection. - The first time a player presses any key that has not yet been claimed, that key is automatically reserved for them. No other player can press that key afterwards.
- The server passes each valid keypress to the compiled C helper, which uses CoreGraphics to emulate the keypress on the host machine in real time.
- Each player can see all of their reserved keys displayed in the Keys panel on the right side of their player page.
What happens next
Once your first session is running, explore the rest of the CollaboKeys documentation to go deeper:- Gameplay — detailed explanation of how key reservation works, what happens when keys run out, and how to refresh or revoke keys mid-session.
- Admin page — full reference for every control available in the admin dashboard, including player management, the waiting room, live logs, and the command input box.
- Configuration — tune server behaviour through
src/config.json: set an admin password, adjust port preferences, limit how many keys each player can reserve, configure the waiting room, and more.