# 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](https://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](https://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](./configuration.md) 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](./configuration.md#command-line-flags-and-environment-variables). ## The manual path You can skip enrollment if you already have a system key. Pass it directly: ```sh daemonitor-client --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](./configuration.md) 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.