monitorat 0.10.1

An offline-embracing, modular, multi-instance monitor for homelabs and Linux computers

[ demo ]

Monitorat is a federated dashboard and documentation system with an extensible widget framework. Its philosophy is to make system monitoring and documentation continuous, much like the way tables and figures are integrated in journal or news articles.

Available widgets:

• metrics
• network
• reminders
• services
• speedtest
• wiki

Widgets have a general, self-contained structure where both API and UI are straightforward to create.

~/.config/monitorat/widgets/
└── my-widget
    ├── api.py
    ├── index.html
    └── app.js

Dashboard documentation is handled through the Wiki widget. Each document snippet added is a new widget instance. This document and any others you add to your wiki will be rendered in GitHub-flavored markdown via markdown-it.

Gallery

It's best to check out the demo which is a fully interactive version of the application you could be running on your machines. Screenshots of the demo are compiled below.

Features

• Beautiful documentation for your Homelab and media servers.
• Completely headless and works offline.
• Responsive design for mobile and desktop, with light and dark modes.
• Track how hot your CPU gets over the course of the day.
• Be alerted when under extremely high load.
• Keep a record of internet speedtests even when AFK.
• List all your reverse-proxied services with offline-friendly bookmarks.
• Even runs on Raspberry Pi 2/3 w/ Pi-Hole, Unraid, and other homelab systems.
• Has federation: you can monitor services, metrics data, and documentation across many machines from a central command.

---

Installation

Both the pip and uv installation methods assume you are using a configuration file at ~/.config/monitorat/config.yaml.

Installing with Pip or uv

PyPI

pip: The simplest way is to install from PyPI:

pip install monitorat
monitorat demo --mode simple

I like uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install monitorat
monitorat demo  # --mode [simple|advanced|federation]

Then open a browser at http://localhost:6100.

From Source

Or install the package from source/development (use -e if you're developing widgets):

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 6161

or run the demos:

monitorat demo --mode simple      # single-instance dashboard
monitorat demo --mode advanced    # single-instance, with feature config examples
monitorat demo --mode federation  # multiple machines, and widget integration examples

which are also held on monitorat.brege.org:

• simple
• advanced
• federation

Monitorat will resolve your config file either at the destination given by -c|--config, or the default location ~/.config/monitorat/config.yaml.

Daemonizing with Systemd

Assuming you'd like to run monitorat 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.

Installing with Docker

See: Docker for running monitorat in a Docker container.

Alternate Installs

See: Alternate Installs for traditional deployments at /opt/monitorat.

---

The Dashboard

Open http://localhost:6161, or your specified port, or configure through a reverse proxy.

Configuration

These are the basic monitorat settings for your system, assuming you want to put all icons, data and the config file in ~/.config/monitorat/ which is the default location.

site:
  name: "@my-nas"
  title: "Dashboard @my-nas"

paths:
  data: data/
  img: img/  # or /home/user/.config/monitorat/img/

widgets: { ... }

# privacy: { ... }
# alerts: { ... }
# notifications: { ... }

Widgets

monitorat has an extensible widget system. You can add any number of widgets to your dashboard multiple times over, re-order them, and enable/disable any you don't need. You can add more widgets from others in ~/.config/monitorat/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/monitorat/widgets/

Each widget can be configured in its own YAML block. To configure a widget in its own file,

includes:
  - "/home/user/.config/monitorat/widgets/my-widget.yaml"

or do this for every widget through config snippets:

includes:
  - include/services.yaml
  - include/metrics.yaml
  - include/reminders.yaml
  - include/network.yaml
  - include/speedtest.yaml
  - include/my-widget.yaml
  - # ... wikis, user widgets, etc

Making your own

They are also quite easy to build. An example of a widget built with Codex in 12 minutes:

• Agentic Archetype: Building Widgets with AI

Services

The Service Status widget is a simple display to show what systemd services, timers, and Docker containers are running or have failed. GitHub - Demo

You can configure the service tiles to have both your URL (or WAN IP) and a local address (or LAN IP) for use offline. monitorat is completely encapsulated and works offline even when internet is down.

Wiki

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. GitHub - Demo

Changing widget order or enabling/disabling widgets is rather straightforward.

widgets:
  enabled: 
    - network
    - network-wiki
    - services
    - services-wiki
    - metrics
    - speedtest
    - ...

monitorat uses GitHub-flavored markdown

System Metrics

Metrics provides an overview of system performance, including CPU, memory, disk and network usage, and temperature over time. Data is logged to metrics.csv. GitHub - Demo

Speedtest

The Speedtest widget allows you to keep a record of your internet performance over time. It does not perform automated runs. GitHub - Demo

Network

The Network widget may be the most specific. This example uses ddclient-style generated logs. GitHub - Demo

The network widget is best used on machines with continuous uptime. You might even keep monitorat running on your pi-hole.

Reminders

The Reminders widget allows you to set reminders for system chores, login/key change reminders, and other one-off chirps. GitHub - Demo

Reminders are facilitated by Apprise (see below).

Privacy

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: true

Running

monitorat config

will print the runtime config with these masks applied.

Alerts

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 warning

Notifications

The notifications system uses Apprise to notify through practically any service, via apprise URLs.

notifications:
  apprise_urls:
    - "pover://abscdefghijklmnopqrstuvwxyz1234@4321zyxwvutsrqponmlkjihgfedcba"
    - "mailto://1234 5678 9a1b [e-mail]?user=[e-mail]&to=[e-mail]"
    - # more apprise urls if needed...

---

Contributors

• contributing

• changelog

• installation index

License

GPLv3