Serve mode

Collect continuously, expose JSON status and provide Prometheus metrics.

After a failed cycle, the dashboard shows the time and contents of the last complete snapshot in read-only mode. There is no history before the first successful cycle.

1. Start the agent

After installation, run in a terminal:

monit-docker serve --interval 30

The first cycle starts immediately. Each cycle is followed by a 30-second wait; this is not a fixed start-to-start period. The default listener is 127.0.0.1:9808. Without rules, it only observes and needs no state file.

2. Check the endpoints

From a second terminal:

curl -fsS http://127.0.0.1:9808/healthz
curl -i http://127.0.0.1:9808/readyz
curl -fsS http://127.0.0.1:9808/v1/status
curl -fsS http://127.0.0.1:9808/metrics

3. Persistent Docker variant

docker run -d --name monit-docker-agent --restart unless-stopped \
  -p 127.0.0.1:9808:9808 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  decryptus/monit-docker:1.3.3 \
  monit-docker serve --bind 0.0.0.0 --interval 30

docker logs monit-docker-agent

Stop the terminal agent before reusing port 9808. The 0.0.0.0 bind is inside the container; the published port stays on host loopback. Stop this variant with docker stop monit-docker-agent.

4. Add a rule

monit-docker --name 'web*' serve --interval 30 \
  --state-file "$HOME/.local/state/monit-docker/web.json" \
  --cooldown 600 --trigger-after 300 --max-gap 120 \
  --dry-run --cmd-if 'mem_percent > 90 ? restart'

This first test performs no actions. After review, remove --dry-run to enable actions and persistent observation tracking. Rules require a state file, including in dry-run. With Docker, mount its entire directory, including the lock.

max-gap must exceed the collection interval. An unconditional --cmd does not wait for trigger-after.

5. Operate the agent

The agent does not terminate TLS. By default, /metrics is open. Set serve --metrics-token-file FILE and configure the scraper with the matching bearer token to require authentication. Use --status-token-file for status reads. Keep it on localhost or a private network. For browser access, install the HTTPS proxy and interface.

By default, snapshots expire after max(90, 3 × interval) seconds. Failed or stale collection hides container metrics. Prometheus stores history; agent snapshots stay in memory.

Ctrl+C or SIGTERM requests shutdown and waits for the current cycle. There is no guaranteed maximum total shutdown time.

The HTTP API and metrics contract covers responses, errors, freshness and exports, with curl examples.

Direct command settings

Each command reads its own section. Explicit CLI flags take precedence. Repeated rule or resource flags replace the corresponding YAML list. An explicit monit --rsc selects observation even if YAML configures an action. Use --dry-run to preview rules for one invocation.

stats:
  rsc: [cpu_percent, mem_usage]
  output: json
serve:
  interval: 60
  status_token_file: /run/secrets/status

To protect GET and HEAD on /v1/status, set serve.status_token_file or --status-token-file to the path of a dedicated secret. Clients send its bearer token. With the dashboard, configure the authenticated proxy to inject the header only on the upstream status route.