daemonitor

Appearance

Getting started ​

daemonitor has two halves. The agent, @daemonitor/client, runs on each machine you want to watch. It runs a set of plugins and pushes each plugin's report to the server. The dashboard at daemonitor.com shows what came in, decides what is healthy, and alerts you when something isn't.

Getting a machine on the board takes three steps. Create an account, add a system in the dashboard, then run one command on the machine.

Requirements ​

  • Node.js 18.17 or newer on the machine you want to monitor.
  • Outbound HTTPS to daemonitor.com. The agent only pushes. Nothing connects in to it.
  • Linux with systemd if you want the agent to install itself as a service. macOS and Windows run the agent fine, but you start it with your own process manager.

Create an account ​

Go to daemonitor.com/register. You can sign up three ways.

  • Email and password.
  • "Continue with Google".
  • "Email me a magic link", which signs you in without a password.

After signing in you land on the fleet view, which is empty until an agent reports.

Add a system ​

A system is one machine running one agent. Click Add system in the top bar. The command palette has the same action.

The dialog asks for two things.

  1. System name. Optional. Leave it blank and the system takes the machine's hostname when the agent checks in.
  2. Plugins. Pick what to monitor. os is selected by default and is always included, because without it a system has no CPU, memory or disk figures. See Configuration for what each plugin does.

Submit, and the dialog shows a command like this:

sh
npx @daemonitor/client --token dmk_enroll_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The token is single use and expires one hour after you create it. It is not your system key. The agent trades it for the key on first run and stores the key itself, so the key never sits in your shell history or the dashboard.

Install the agent with the enrollment command ​

Run the command on the machine. On first run the agent:

  1. Sends the token to POST /api/enroll/claim, along with the hostname, OS details and a list of plugins it detected on the box.
  2. Receives the system key and a starting client.config.json.
  3. Writes credentials.json and client.config.json to its state directory.
  4. Starts reporting.

The dialog in the dashboard switches from "Waiting for the agent" to "connected" as soon as the claim lands.

The state directory is chosen in this order:

  1. --dir or DAEMONITOR_DIR, if set.
  2. Under sudo, the invoking user's ~/.config/daemonitor, not root's.
  3. /etc/daemonitor when running as root and the directory is writable.
  4. $XDG_CONFIG_HOME/daemonitor, or ~/.config/daemonitor.
  5. The current working directory.

credentials.json is written with mode 0600. It holds the system key, the system id and the API endpoint the key belongs to.

If the claim fails, the agent says why. An unknown token returns 401, a used token returns 409 and an expired token returns 410. Generate a new one from Add system in each case. Network errors retry five times with backoff.

If a client.config.json already exists on the machine, enrollment leaves it alone. A file you edited by hand wins over the generated one.

Keep it running ​

An agent started from a terminal dies with the terminal. Pick one of the options below.

systemd, installed by the agent ​

When you enroll from an interactive terminal on Linux with systemd, the agent asks:

Keep this running at boot? [Y/n]

Answer yes and it writes /etc/systemd/system/daemonitor-client.service, then enables and starts it. This needs root.

The unit must point at a durable install, and npx runs out of a cache that npm can clear at any time. The agent refuses to write a unit that points into that cache. Install the package globally first:

sh
sudo npm install -g @daemonitor/client
sudo daemonitor-client --token dmk_enroll_xxxxxxxx --install-service

--install-service enrolls if needed, writes the config, installs the unit and exits. systemd then starts its own copy. The unit runs as the user who ran sudo, not as root, so the docker and lxc plugins reach their sockets through that user's group membership. It restarts on failure after 10 seconds and waits for network-online.target.

Check on it with:

sh
systemctl status daemonitor-client
journalctl -u daemonitor-client -f

A reference copy of the unit ships in the package at etc/daemonitor-client.service, if you would rather place it yourself. Edit User and WorkingDirectory to match the account whose ~/.config/daemonitor holds the credentials.

pm2 ​

If you already run pm2, install globally and hand the binary to pm2:

sh
npm install -g @daemonitor/client
daemonitor-client --token dmk_enroll_xxxxxxxx   # enroll once, answer n to the service prompt, then Ctrl-C
pm2 start "$(command -v daemonitor-client)" --name daemonitor-client
pm2 save

The second run needs no token. The agent reads its stored credentials.

Containers and config management ​

Every flag has an environment variable, so the same options work in a systemd EnvironmentFile or with docker run -e. See Configuration.

The manual path ​

You can skip enrollment if you already have a system key. Pass it directly:

sh
daemonitor-client --key <system key>

or set DAEMONITOR_KEY. With a key and no config file, the agent runs the os plugin alone. Add a client.config.json to choose plugins. The Configuration page covers the file.

The dashboard does not display a system key. The way to get one is to enroll once and read systemKey out of credentials.json. Each system has one key, and every agent that pushes with it reports into the same system. Use one key per machine, or two hosts will overwrite each other's rows.

If the server answers 404 to a push, the key no longer matches a system. The system was probably deleted. Re-enroll with a fresh token.

What to check after install ​

  • The system shows up in the fleet with a name and an IP within one plugin interval. The os plugin reports every 30 seconds by default.
  • The agent prints its version, endpoint, config path and active plugins at startup. If a plugin you expected is missing from that list, its name in the plugins array is wrong or the agent doesn't ship it.
  • Run daemonitor-client --help for the full flag list and daemonitor-client --version for the installed version.