Getting started

Requirements

Hyperwatch runs on Node.js 24 or later. We recommend nvm: nvm install && nvm use.

Install

Install the CLI globally from npm:

npm install -g @hyperwatch/hyperwatch

Or clone the repository to hack on it:

git clone https://github.com/hyperwatch/hyperwatch.git
cd hyperwatch
npm install

Start

npm start

This loads the default configuration, and is the same as:

npm start config/default

The default configuration listens for:

Input	Where	Format
Syslog	port 1514	nginx combined
Syslog	port 1515	nginx hyperwatch_combined
Syslog	port 1516	Hyperwatch JSON
HTTP	POST /input/log	Hyperwatch JSON
WebSocket	/input/log	Hyperwatch JSON

The Hyperwatch API and WebSocket are served on port 3000. Open http://localhost:3000/status to check your inputs.

Enable modules

Only the status module is active by default. Enable the others in a .hyperwatchrc file in your working directory, for example to watch live logs at /logs/main and rank addresses at /addresses:

{
  "modules": {
    "logs": { "active": true },
    "agent": { "active": true },
    "address": { "active": true }
  }
}

See Configuration for every module.

Configure

Connect Hyperwatch to your traffic sources by creating your own configuration file, such as config/custom.js:

module.exports = function (hyperwatch) {
  const { pipeline, input, format } = hyperwatch;

  hyperwatch.init();

  const nginxInput = input.file.create({
    path: '/var/log/nginx/access.log',
    parse: format.nginx.parser({ format: format.nginx.formats.combined }),
  });

  pipeline.registerInput(nginxInput);
};

Then start Hyperwatch with it:

npm start config/custom

Change the port with an environment variable:

PORT=80 npm start config/custom

Next steps

• Inputs & formats: every input type and log format, with examples.
• Configuration: constants in a .hyperwatchrc file.
• Firewall: tag listed IPs and User-Agents, and sync the lists with Cloudflare.
• Tutorials for Apache and Express.