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.

All CollaboKeys behavior is controlled by a single file — src/config.json. The file is read once at server boot, so changes take effect on the next server start. No live reload or restart mid-session is required for most settings, since they are applied during initialization.

​
Default configuration

src/config.json
{
    "adminPage": {
        "enabled": true,
        "password": "",
        "autoAuthHost": true
    },
    "app": {
        "preventDisplaySleep": true,
        "splashScreenTime": 1000,
        "enableDevTools": false
    },
    "console": {
        "enabled": true
    },
    "logs": {
        "logPage": {
            "enabled": true
        },
        "logFileTypes": [
            "combined",
            "error",
            "warn"
        ],
        "deleteAtStart": false
    },
    "player": {
        "name": {
            "minLength": 3,
            "maxLength": 20,
            "regex": "[a-zA-Z0-9]"
        },
        "waitRoomWhenJoined": false,
        "maxReservedKeys": 0
    },
    "server": {
        "ports": [3000, 8080, 8000, 5000, 2000, 4000, 6000, 7000, 9000]
    },
    "allowHeldKeys": true,
    "allowEmulationAtStart": true,
    "allowReservationAtStart": true,
    "maxKeypressesPerMinute": 150
}

​
Admin Page (adminPage.*)

​
adminPage.enabled
boolean
default:"true"
Enable the admin page. Set to false to rely solely on the CLI console for server controls. When disabled, any WebSocket connection to the /admin namespace is immediately rejected and disconnected.
​
adminPage.password
string
default:"\"\""
Password required to authenticate on the admin page. An empty string ("") means no password is required — any visitor to the admin page is granted access automatically. It is strongly recommended to set a password when the server is accessible to others on the network.
​
adminPage.autoAuthHost
boolean
default:"true"
Automatically authenticate connections that originate from localhost (127.0.0.1 or ::1). When enabled, the host opening the admin page on their own machine is granted admin access without entering a password — even when a password is configured for remote users.

​
Electron App (app.*)

These settings only apply when running CollaboKeys as an Electron app via npm start. They are ignored when running the server headlessly with npm test.
​
app.preventDisplaySleep
boolean
default:"true"
Prevents macOS from sleeping the display while CollaboKeys is open. Uses Electron’s powerSaveBlocker API with the prevent-display-sleep mode. If the blocker fails to start, a warning is logged but the app continues normally.
​
app.splashScreenTime
number
default:"1000"
Minimum time in milliseconds that the splash screen is shown before the app switches to the admin dashboard. If the server starts faster than this value, the app waits for the remainder. If the server takes longer, the splash screen stays until the server is ready regardless of this setting.
​
app.enableDevTools
boolean
default:"false"
Allows Chromium DevTools to be opened inside the Electron window. Not recommended for production use — enabling this exposes the full browser developer toolset to anyone with physical access to the host machine.

​
Console (console.*)

​
console.enabled
boolean
default:"true"
Enables CLI console commands in the terminal. When set to false, the readline interface is still initialized but all input is ignored. Disable this if you want to prevent keyboard interaction with the running process without fully detaching stdin.

​
Logging (logs.*)

​
logs.logPage.enabled
boolean
default:"true"
Enables the /logs, /logs/error, and /logs/warn HTTP endpoints. When enabled, anyone who can reach the server can view log output in their browser. Disable this if you want to restrict log access to the host machine only.
​
logs.logFileTypes
array
default:"[\"combined\", \"error\", \"warn\"]"
An array of Winston transport names that determine which log files are created in the logs/ directory. Each entry in the array becomes a separate log file (e.g., logs/combined.log, logs/error.log, logs/warn.log). These same names are used as URL paths under /logs/.
​
logs.deleteAtStart
boolean
default:"false"
Clears all files in the logs/ directory each time the server starts. Useful for keeping disk usage low during repeated testing sessions. Set to false to preserve logs across restarts for post-session review.

​
Player (player.*)

​
player.name.minLength
number
default:"3"
Minimum username length, inclusive. Players submitting a name shorter than this value receive an error and must choose a longer name before they can interact with the game.
​
player.name.maxLength
number
default:"20"
Maximum username length, inclusive. Players submitting a name longer than this value receive an error and must shorten their name.
​
player.name.regex
string
default:"\"[a-zA-Z0-9]\""
A regular expression pattern tested against a player’s submitted username. The name is accepted only if the pattern matches. The default pattern [a-zA-Z0-9] ensures names contain at least one alphanumeric character, preventing blank or symbol-only names.
​
player.waitRoomWhenJoined
boolean
default:"false"
When set to true, newly connected players are automatically placed in the waiting room instead of joining the active session immediately. The admin must explicitly admit them using the waitingroom admit <id/all> command or the admin page controls.
​
player.maxReservedKeys
number
default:"0"
Maximum number of keys a single player can reserve. Once a player reaches this limit, additional keypresses will not claim new keys for them. Set to 0 to impose no limit, allowing each player to accumulate as many keys as they press.

​
Server (server.*)

​
server.ports
array
Port preference order for the HTTP server. CollaboKeys tries each port in sequence; if a port is already in use (EADDRINUSE), it moves to the next. If all listed ports are unavailable, the server falls back to port 0, which asks the OS to assign a random available port.

​
Global options

​
allowHeldKeys
boolean
default:"true"
When true, keydown and keyup events are emulated separately, allowing keys to be physically held down in the target game for as long as the player holds them in their browser. When false, every keypress is treated as a quick tap — a keydown followed immediately by a keyup — regardless of how long the player holds the key.
​
allowEmulationAtStart
boolean
default:"true"
Whether keyboard emulation is active when the server first starts. If set to false, the server accepts keypresses from players but does not forward them to the OS until emulation is manually enabled via the enable emulation command or admin page.
​
allowReservationAtStart
boolean
default:"true"
Whether automatic key reservation is active when the server starts. When true, the first player to press an unclaimed key is assigned that key. When false, keypresses are processed but keys are not automatically reserved until reservation is manually enabled.
​
maxKeypressesPerMinute
number
default:"150"
Global rate limit for keypresses across all connected players per clock minute. Once the limit is reached, further keypresses are dropped until the next minute begins. Set to 0 to disable rate limiting entirely.

​
Editing the config file

The configuration file is located at src/config.json relative to the project root. It can be edited with any text editor — VS Code, nano, vim, or any JSON-capable editor. After saving your changes, restart the server for them to take effect.
Do not delete any keys from the JSON object. Missing keys may fall back to internal defaults, but they will produce warnings in the log output and can cause unexpected behavior. Always keep the full structure intact, only changing the values you need to adjust.

Build docs developers (and LLMs) love

Get started for freeTalk to us