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 JSON logging. Every significant event — player connections, keypresses, server startup, and errors — is captured with a timestamp and written to rotating log files. Logs can also be viewed live in the admin panel or fetched via HTTP at any time.

​
Log Levels

Winston log levels are ordered by descending severity. CollaboKeys uses the following levels:
LevelSeverityExamples
errorHighestKey emulation failure, accessibility helper crash
warnWrong OS detected, display sleep preventer failed to start
infoPlayer keypress, username set, server started on port
httpClient connected, admin disconnected
verboseConsole command ran with full response text
debugInternal state transitions
sillyLowestFine-grained diagnostic output
The logger is initialized at level info, meaning http, verbose, debug, and silly messages are not written to file or displayed in the console by default unless you explicitly add a transport for that level via logs.logFileTypes.

​
Log Files

​
Location

Log files are written to the logs/ folder. The exact path depends on how CollaboKeys is running:
  • Running from source (npm start / npm test): logs/ folder inside the project directory, i.e. <project root>/logs/
  • Packaged as a .app: macOS userData path (typically ~/Library/Application Support/CollaboKeys/logs/)
The resolved path is printed to the terminal on startup: 
Log files at /Users/you/Library/Application Support/CollaboKeys/logs

​
Default Log Files

By default, the logs.logFileTypes array in config.json is ["combined", "error", "warn"], which produces three files:
FileLevel FilterWhat’s inside
error.logerror and aboveMajor failures — emulation errors, crashes
warn.logwarn and aboveWarnings and errors — minor issues and above
combined.logAll levels (no filter)Everything: errors, warnings, info, http, etc.
To capture more detail, add "verbose" or "debug" to logs.logFileTypes in config.json. For example:
"logFileTypes": ["combined", "error", "warn", "verbose"]
This creates an additional verbose.log file containing verbose, http, info, warn, and error entries.

​
Configuring Log Files

Log file behavior is controlled by two options in config.json:
  • logs.logFileTypes — array of level names and/or "combined". Each entry creates a corresponding <name>.log file. Valid values: error, warn, info, http, verbose, debug, silly, combined. Unknown values are silently skipped.
  • logs.deleteAtStart — set to true to wipe the entire logs/ directory each time the server starts, giving you a fresh log on every session.

​
Raw Log Format

Each line written to a log file is a JSON object: 
{"level":"info","message":"Valid keypress from Alice (#3): ArrowUp.","timestamp":"2026-01-15T20:04:11.032Z"}
{"level":"error","message":"Error emulating keypress: RobotJS returned null","timestamp":"2026-01-15T20:04:12.891Z"}
{"level":"http","message":"Player #5 disconnected.","timestamp":"2026-01-15T20:04:45.210Z"}

​
HTTP Log Pages

When logs.logPage.enabled is true (the default), CollaboKeys exposes log files over HTTP so they can be read from any browser or curl command without needing filesystem access.

​
Endpoints

PathLog File Served
GET /logscombined.log
GET /logs/combined.log
GET /logs/errorerror.log
GET /logs/warnwarn.log
GET /logs/<name><name>.log (any valid log filename)

​
Response Format

The HTTP endpoint returns text/plain — not raw JSON. Each log entry is formatted for readability, with the level as a prefix and multi-line messages indented to align with the first line: 
INFO: Server started on port 3000.
INFO: Valid keypress from Alice (#3): ArrowUp.
INFO: Valid keypress from Bob (#7): ArrowLeft.
HTTP: Player #5 disconnected.
ERROR: Error emulating keypress: RobotJS returned null
WARN: Display sleep preventer failed to start: Error: ...
Multi-line messages (for example, a stack trace in a verbose command response) are indented so each continuation line aligns under the first: 
VERBOSE: Console command "list all" ran with response:
         #1 Alice  — keys: [ArrowUp, ArrowDown]
         #2 Bob    — keys: [ArrowLeft, ArrowRight]

​
404 Responses

The /logs endpoint returns a 404 with a plain-text body in two situations:
  • The requested log file does not exist on disk (e.g. you visit /logs/debug but debug is not in logs.logFileTypes).
  • logs.logPage.enabled is set to false in config.json.
If the log file exists but is empty, the endpoint returns 200 with the body Logs empty rather than an empty response.

​
Admin Panel Log Stream

The admin panel receives log messages in real time via Socket.IO. This is powered by the AdminPageTransport class in log.js, a custom Winston transport that emits a log Socket.IO event to all authenticated admins in the admin room whenever a new log entry is produced. The transport is registered at the http level, so the admin panel receives http, info, warn, and error messages live.

​
Display Formatting

The admin panel applies visual styling based on log level:
LevelAdmin Panel Appearance
errorEntire message bolded and colored red, prefixed with ERROR:
warnEntire message bolded and colored red, prefixed with WARNING:
All othersOnly the level prefix is bolded; message text is unstyled
The admin panel log stream requires the admin page to be enabled (adminPage.enabled: true). If the admin page is disabled, the AdminPageTransport is never registered and no Socket.IO log events are emitted.

​
Console Output

In non-production environments (when NODE_ENV is not set to "production"), log messages are also printed to stdout in your terminal. The console format is a compact single-line string: 
INFO: Server started on port 3000.
WARN: Display sleep preventer failed to start: ...
ERROR: Error emulating keypress: ...
When running CollaboKeys with npm test for development, console output is active by default. When running the packaged .app, NODE_ENV is set to "production" and console output is suppressed — use the HTTP log pages or admin panel stream instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us