e24f5b6f00
Zero-dependency local agent: collect one snapshot through the shared metrics.js, POST it once to /hosts/<id>, exit. Cron runs it every five minutes. Nothing is queued and nothing is replayed — a heartbeat from five minutes ago describes a machine that no longer exists, so a failed push is logged and dropped rather than spooled. run-push.sh sources ~/.config/maximus-host-agent.env (mode 600), refuses to start when HOSTS_API_URL, HOSTS_INGEST_TOKEN or HOST_ID is missing, and never enables shell tracing: the script is meant to be piped into `logger`, where `set -x` would echo the ingest token into /var/log/syslog and journald for good. Same reason the failure path reports only err.code and the HTTP status — never an error object, request options, headers, or a response body. The cost is accepted: a 400 says the payload was rejected, not why. 50 tests, including two that spawn the real process against a failing server and scan its actual stdout and stderr for any five-character fragment of the token. The payload is pinned against the server's own sanitizeSnapshot(), and one case pushes a real collectMetrics() snapshot through the real ingestion handler, so a drift between agent and server turns a test red instead of producing a 400 at 3 a.m. on the ThinkPad. agent/ stays out of the Docker image: the COPY line is untouched, and a test pins that it copies files one by one and never names the directory. Installing on a workstation — frozen copy, env file, crontab line, dry run, and why two machines must never share a HOST_ID — is documented in agent/README.md. The install itself belongs to the commissioning issue. Resolves #15
170 lines
6.1 KiB
Markdown
170 lines
6.1 KiB
Markdown
# Workstation agent
|
|
|
|
Collects one snapshot of the machine it runs on and pushes it to
|
|
`POST /hosts/<id>` on the health API. Cron runs it every 5 minutes; the
|
|
dashboard reads the result through `GET /hosts`.
|
|
|
|
Zero dependencies — `node:http` / `node:https` and the `metrics.js` already
|
|
shared with the server. Node 22+.
|
|
|
|
| File | Role |
|
|
|------|------|
|
|
| `push-metrics.js` | Collect, build the payload, POST once, exit |
|
|
| `run-push.sh` | Cron wrapper: load the env file, check the install, exec node |
|
|
|
|
This directory is **not** part of the server image: the `Dockerfile` copies
|
|
`package.json index.js metrics.js` one by one, and a test pins that it stays
|
|
that way. The agent ships by copying files onto a workstation, never by deploy.
|
|
|
|
## What it deliberately does not do
|
|
|
|
**No queue, no replay.** One run is one attempt. A push that fails is dropped,
|
|
logged, and the process exits non-zero — the next beat is five minutes away and
|
|
a heartbeat from five minutes ago describes a machine that no longer exists.
|
|
Nothing is spooled to disk, so nothing can ever be replayed to make the
|
|
dashboard show a past that is no longer true.
|
|
|
|
**No secret in the logs.** `run-push.sh` is meant to be piped into `logger`, so
|
|
everything the agent prints ends up in syslog and journald permanently. The
|
|
failure path therefore reports **only** `err.code` and the HTTP status — never
|
|
an error object, never the request options, never a response body, and never a
|
|
header. That is also why `run-push.sh` must never gain a `set -x`: the shell
|
|
would echo the token as it sources the env file.
|
|
|
|
The cost is real and accepted: a `400` tells you the server rejected the
|
|
payload, not why. The reason is in the server's logs, and `--dry-run` (below)
|
|
shows you the exact payload that was sent.
|
|
|
|
## Install on a new workstation
|
|
|
|
### 1. Freeze a copy
|
|
|
|
The cron must point at a copy, **never at the git working tree**. The server is
|
|
deployed by a manual trigger, so the checked-out repo drifts freely: a branch
|
|
checkout in `~/claude-code/vps-health-api` would silently change — or break —
|
|
the heartbeat of the workstation, and nothing would say so.
|
|
|
|
`push-metrics.js` loads `metrics.js` from one directory up, so the copy keeps
|
|
the repo layout:
|
|
|
|
```
|
|
mkdir -p ~/.local/share/maximus-host-agent/agent
|
|
cp metrics.js ~/.local/share/maximus-host-agent/
|
|
cp agent/push-metrics.js agent/run-push.sh ~/.local/share/maximus-host-agent/agent/
|
|
chmod +x ~/.local/share/maximus-host-agent/agent/run-push.sh
|
|
```
|
|
|
|
Re-run those three `cp` after any change to the agent — that copy step *is* the
|
|
deployment.
|
|
|
|
### 2. Write the env file
|
|
|
|
`~/.config/maximus-host-agent.env`, mode `600` (the agent warns on any other
|
|
mode). Use `printf`, not a heredoc: a trailing newline or space inside the token
|
|
value is the most common install failure.
|
|
|
|
```
|
|
HOSTS_API_URL=https://health.lacompagniemaximus.com
|
|
HOSTS_INGEST_TOKEN=<the ingest token>
|
|
HOST_ID=thinkpad
|
|
# NODE_BIN=/usr/bin/node # only if cron cannot find node (see below)
|
|
```
|
|
|
|
```
|
|
chmod 600 ~/.config/maximus-host-agent.env
|
|
```
|
|
|
|
`HOSTS_INGEST_TOKEN` is the write-only token: it can push snapshots and nothing
|
|
else. It is deliberately *not* `HEALTH_TOKEN` — a stolen workstation must not
|
|
grant read access to the Defenseurs reports.
|
|
|
|
`HOST_ID` must match `^[a-z0-9][a-z0-9-]{0,31}$` and be listed in the server's
|
|
`HOSTS_ALLOWED_IDS`, otherwise the push comes back `403`.
|
|
|
|
### 3. Dry run
|
|
|
|
Collect and print the payload without touching the network or needing any
|
|
config:
|
|
|
|
```
|
|
node ~/.local/share/maximus-host-agent/agent/push-metrics.js --dry-run
|
|
```
|
|
|
|
Then one real push, by hand, before installing the cron:
|
|
|
|
```
|
|
~/.local/share/maximus-host-agent/agent/run-push.sh
|
|
# host-agent: ok id=thinkpad status=204 hostname=thinkpad-x1
|
|
```
|
|
|
|
Confirm the server side (from a machine that holds `HEALTH_TOKEN`):
|
|
|
|
```
|
|
curl -H "Authorization: Bearer $HEALTH_TOKEN" \
|
|
https://health.lacompagniemaximus.com/hosts
|
|
```
|
|
|
|
The entry for your id should show `online: true` and a small `ageSeconds`.
|
|
|
|
### 4. Install the cron
|
|
|
|
```
|
|
crontab -e
|
|
```
|
|
|
|
```
|
|
*/5 * * * * $HOME/.local/share/maximus-host-agent/agent/run-push.sh 2>&1 | logger -t host-agent
|
|
```
|
|
|
|
Read what it did:
|
|
|
|
```
|
|
journalctl -t host-agent --since -1h
|
|
```
|
|
|
|
If the line works by hand but produces nothing under cron, it is almost always
|
|
`node`: cron's `PATH` is `/usr/bin:/bin`, and a node installed by nvm or under
|
|
`/usr/local` is not on it. Set `NODE_BIN` to an absolute path in the env file —
|
|
the wrapper says so explicitly rather than failing silently.
|
|
|
|
## One id per workstation
|
|
|
|
The server keeps **one file per host id** and the last write wins. Two
|
|
workstations configured with the same `HOST_ID` therefore overwrite each other
|
|
every five minutes, and nothing anywhere reports an error: the dashboard shows
|
|
one host that looks perfectly healthy while its numbers come from whichever
|
|
machine pushed last.
|
|
|
|
The signal to watch for is the `hostname` field in `GET /hosts` **changing
|
|
between polls** while the id stays the same — plus CPU and memory that jump
|
|
around without pattern. If you see that, two machines are sharing an id.
|
|
|
|
Give every workstation its own id and add it to `HOSTS_ALLOWED_IDS` on the
|
|
server before installing the agent on it.
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | Snapshot accepted (server answered 2xx, normally `204`) |
|
|
| 1 | Install problem: env file missing, a variable unset, malformed `HOST_ID`, node not found, `metrics.js` not found next to the agent |
|
|
| 2 | The push did not land: network error (`code=…`) or a non-2xx answer (`HTTP …`) |
|
|
|
|
A `1` needs a human on the workstation. A `2` usually fixes itself on the next
|
|
beat; a `2` that repeats for an hour means the API or the link is down.
|
|
|
|
## Payload
|
|
|
|
Exactly the `GET /health` body minus `logto` and `timestamp`:
|
|
|
|
```
|
|
{ hostname, uptime,
|
|
cpu: { model, cores, loadAvg, usagePercent },
|
|
memory: { totalGB, usedGB, freeGB, usagePercent },
|
|
disk: { totalGB, usedGB, freeGB, usagePercent } }
|
|
```
|
|
|
|
Sharing `metrics.js` with the server keeps the two in step, but it is not the
|
|
guarantee — the frozen copy can lag behind a deployed server. The real contract
|
|
is the server's own validation, and `__tests__/agent.test.js` checks the agent's
|
|
payload against it (including a real snapshot through the real handler).
|