[ demo ]
This file is monitor@'s README, which is the default document served in the web UI. Document rendering is but one widget available in monitor@.
Available widgets:
Widgets have a general, self-contained structure where both API and UI are straightforward to create.
~/.config/monitor@/widgets/
└── my-widget
├── api.py
├── index.html
└── app.js
You can also add your own documentation through the Wiki widget, which may help you or your loved ones figure out how your headless homelab or riceware works. This document and any others you add to your wiki will be rendered in GitHub-flavored markdown via markdown-it.
But you want an actual monitor or dashboard.
 |
 |
 |
 |
 |
- See how hot your CPU got today.
- Be alerted when under high load.
- Keep a record of and graph your internet speed.
- List of all your reverse-proxied services with offline-friendly bookmarks.
Both installation methods assume you are using a configuration file at ~/.config/monitor@/config.yaml.
PyPI: The simplest way is to install from PyPI.
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install monitoratSource: Or install the package from source/development:
git clone https://github.com/brege/monitorat.git
cd monitorat
uv tool install -e .In either case, start the server:
monitorat -c path/to/config.yaml server --host 0.0.0.0 --port 6161or run the demo:
monitorat -c demo/config.yaml serverAssuming you'd like to run monitor@ as a systemd service with your normal user, group, and hostname:
bash <(curl -s https://raw.githubusercontent.com/brege/monitorat/refs/heads/main/scripts/install-systemd-uv.sh)This pulls the uv-flavored systemd script from scripts/install-systemd-uv.sh, using sudo internally to install the systemd unit to /etc/systemd/system/monitor@.service.
For alternate installs, see docs/install.md to install monitor@/monitorat => /opt/monitor@ and other deployments.
Open http://localhost:6161 or configure this through a reverse proxy. If you're just interested in playing with a read-only version, check out the demo.
These are the basic monitor@ settings for your system, assuming you want to put all icons, data and the config file in ~/.config/monitor@/ which is the default location.
site:
name: "@my-nas"
title: "Dashboard @my-nas"
paths:
data: data/
img: img/ # or /home/user/.config/monitor@/img/
widgets: { ... }
# privacy: { ... }
# alerts: { ... }
# notifications: { ... }monitor@ is an extensible widget system. You can add any number of widgets to your dashboard, re-order them, and enable/disable any you don't need. You can add more widgets from others in ~/.config/monitor@/widgets/.
widgets:
enabled: # dashboard positions: from top to bottom
- services
- services-wiki # type: wiki
- metrics
- metrics-wiki # type: wiki
- # reminders # '#' disables this widget
- network
- speedtest
- my-widget # in ~/.config/monitor@/widgets/Each widget can be configured in its own YAML block. To configure a widget in its own file,
includes:
- "/home/user/.config/monitor@/widgets/my-widget.yaml"or do this for every widget:
includes:
- include/services.yaml
- include/metrics.yaml
- include/reminders.yaml
- include/network.yaml
- include/speedtest.yaml
- include/my-widget.yaml
- # ... wikis, user widgets, etcThey are also quite easy to build. Example of a widget built with Codex in 12 minutes:
The Service Status widget is a simple display to show what systemd service daemons, timers and docker containers are running or have failed.
You can configure the service tiles to have both your URL (or WAN IP) and a local address (or LAN IP) for use offline. monitor@ is completely encapsulated and works offline even when internet is down.
Some widgets you may want to use more than once. For two markdown documents ("wikis"), use type: wiki. wiki: <title> may only be used once.
Changing widget order or enabling/disabling widgets is rather straightforward.
widgets:
enabled:
- network
- network-wiki
- services
- services-wiki
- metrics
- speedtest
- ...monitor@ uses GitHub-flavored markdown
Metrics provides an overview of system performance, including CPU, memory, disk and network usage, and temperature over time. Data is logged to metrics.csv.
The Speedtest widget allows you to keep a record of your internet performance over time. It does not perform automated runs.
The Network widget may be the most specific. This example uses ddclient-style generated logs.
The network widget is best used on machines with continuous uptime. You might even keep monitor@ running on your pi-hole.
The Reminders widget allows you to set reminders for system chores, login/key change reminders, and other one-offs chirps.
Reminders are facilitated by Apprise (see below).
The privacy mask helps share your setup online without exposing personal information. Those are just string replacements; add as many as you like.
privacy:
replacements:
my-site.org: example.com
my-hostname: masked-hostname
...
mask_ips: trueRunning
monitorat configwill print the runtime config with these masks applied.
Alerts are tied to system metrics, where you set a threshold and a message for each event.
Alerts example configuration
alerts:
cooldown_minutes: 60 # Short cooldown for testing
rules:
high_load:
threshold: 2.5 # load average (e.g., the '1.23' in 1.23 0.45 0.06)
priority: 0 # normal priority
message: High CPU load detected
high_temp:
threshold: 82.5 # celsius
priority: 1 # high priority
message: High temperature warning
low_disk:
threshold: 95 # percent
priority: 0 # normal priority
message: Low disk space warningThe notifications system uses Apprise to notify through practically any service, via apprise URLs.
notifications:
apprise_urls:
- "pover://abscdefghijklmnopqrstuvwxyz1234@4321zyxwvutsrqponmlkjihgfedcba"
- "mailto://1234 5678 9a1b 0c1d@sent.com?user=main@fastmail.com&to=alias@sent.com"
- # more apprise urls if needed...See installing from source for initializing a development server and alternative deployment methods.
For all other development, see contributing.