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.

CollaboKeys uses Winston for structured logging. All significant server events — player connections, name changes, keypresses, emulation errors — are captured and written to log files on disk. At the same time, log entries are streamed in real time to every authenticated admin page session over Socket.IO, so you can monitor activity without opening a terminal.

​
Log Files

Logs are written to the logs/ directory inside the project folder. When running the packaged Electron app, the logs/ folder is placed in the macOS user data directory instead of the project root. Three log files are created by default, controlled by the logs.logFileTypes array in src/config.json:

error.log

Contains error level entries only. These represent major failures — for example, a keyboard emulation error caused by a missing accessibility permission.

warn.log

Contains warn and error level entries. Because Winston transports capture the configured level and everything more severe, setting this transport to warn also includes error entries alongside minor issues like unsupported OS warnings.

combined.log

Contains error, warn, and info level entries together. Info entries include all player activity: keypresses, connections, name changes, and admin authentications.
deleteAtStart — By default this is false, so log files accumulate across server restarts. Set it to true in src/config.json to clear the entire logs/ folder each time the server starts.
src/config.json
{
  "logs": {
    "logPage": {
      "enabled": true
    },
    "logFileTypes": ["combined", "error", "warn"],
    "deleteAtStart": false
  }
}

​
Log Levels

Winston uses a numeric priority system. CollaboKeys emits log entries at four levels, listed from highest to lowest severity:
LevelPriorityUsed for
error0Major failures (e.g. emulation error, server crash)
warn1Minor issues (e.g. unsupported OS, configuration problem)
info2Normal player activity (keypresses, connections, name changes)
http3Socket.IO connect and disconnect events
The combined.log file captures error, warn, and info. The error.log transport is set to error level so it captures only error entries. The warn.log transport is set to warn level, so it captures warn and error entries (Winston captures the configured level and everything more severe). The http level is not written to any log file by default — the logger’s base level is info (priority 2), and since http has priority 3 (lower importance), it falls below the threshold. Http events are streamed to the admin page transport, which is configured at http level separately.

​
Admin Page Logs Panel

The admin page streams log entries in real time so you can monitor the session without keeping a terminal window open.
1

Connect and authenticate

Open the admin page at http://<host-ip>:<port>/admin and authenticate. The Logs panel appears at the bottom of the page once authenticated.
2

Watch live entries

As events occur on the server — players joining, keys being pressed, errors being raised — new entries are prepended to the Logs panel automatically. No refresh is needed.
3

Read the colour coding

Log entries are styled based on their level:
  • Red / bold — error entries (ERROR: <message>) and warn entries (WARNING: <message>)
  • Normal with bold level prefix — info and http entries
4

Clear the panel

Click the clear logs button in the Controls section to empty the Logs panel in your browser. This does not delete or modify any log files on disk.
The admin page transport captures log entries at the http level and above — meaning all four levels (error, warn, info, http) are streamed to the admin page. Only authenticated admins (those who have joined the admin Socket.IO room) receive these events.

​
Log HTTP Pages

CollaboKeys serves log file content over HTTP so you can read logs in any browser without accessing the host filesystem directly. This feature requires logs.logPage.enabled to be true in src/config.json (the default).
URLContent
/logscombined.log — errors, warnings, and info
/logs/errorerror.log — error level only
/logs/warnwarn.log — warn and error levels
/logs/<name>Any log file matching <name>.log in the logs folder
Log content is served as formatted plain text. Each JSON log entry is parsed and rendered as LEVEL: message, with multi-line messages indented to align under the level prefix. If the log file is empty, the page shows Logs empty. If no matching file exists, the server returns 404 Log file not found. Example URLs: 
http://192.168.1.10:3000/logs
http://192.168.1.10:3000/logs/error
http://192.168.1.10:3000/logs/warn
You can also reach these pages through the admin dashboard — click the show button next to the logs dropdown (select the log type first), and the page opens in a new browser tab.

​
Disabling Log Pages

If you do not want log content to be accessible over HTTP, set logs.logPage.enabled to false in src/config.json:
src/config.json
{
  "logs": {
    "logPage": {
      "enabled": false
    }
  }
}
When disabled, any request to /logs or /logs/<name> returns 404 Log page is disabled. Log files on disk are unaffected — they continue to be written normally.

Build docs developers (and LLMs) love

Get started for freeTalk to us