monitorat 0.14.3

A federate, offline-friendly dashboard and documentation system for Linux homelabs

[ demo ]

Monitorat is a federated dashboard and documentation system.

Its philosophy is to make system monitoring and documentation continuous, much like the way tables and figures are integrated within journal articles or Wikipedia.

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
    ├── default.yaml
    ├── index.html
    └── app.js

Documentation is editable in-browser and handled by proliferating Wiki widgets across your dashboard. Each document fragment added is a new widget instance. All documents you add to your wiki will be rendered in GitHub-flavored Markdown via markdown-it.

Gallery

The Demo is a fully interactive version of the application and provides complete resource parity between widget layouts and their YAML config snippets. In that sense, the demo is the documentation.

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

PyPI

Try the demo in 3 seconds:

uv tool install monitorat && monitorat demo

Then open http://localhost:6100.

See: Package Install for installing from PyPI with pip or uv.

Docker

See: Docker Install for installation in a container.

Source

See: Source Install for git-based installations or deployments to /opt.

---

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 keep all icons and data close to your config file (usually ~/.config/monitorat/):

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

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.

Configuration

You can add more widgets of other origin in ~/.config/monitorat/widgets/.

widgets:
  enabled:             # dashboard positions: from top to bottom
    - my-server-notes  # type: wiki
    - services
    - metrics
    - # 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:
  - snippets/services.yaml
  - snippets/metrics.yaml
  - # ... wikis, user widgets, etc

Making your own

Widgets are also quite easy to build with AI. Widget built with Codex in 12 minutes:

Agentic Archetype: Building Widgets with AI

Available Widgets

Services

• monitor systemd services, timers, and Docker containers in real time
• can be used as homelab bookmarks in compact cards layout
• simultaneously provides both your URL (or WAN IP) and local address (or LAN IP) for use offline
• monitorat is completely encapsulated and works offline even when internet is down

Wiki

• uses markdown-it and GitHub-flavored markdown
• can columnate multiple documents/Markdown fragments
• editor can be used to spruce up system docs in the browser
• supports Mermaid diagrams
• inline LaTeX math via KaTeX
• supports GitHub admonitions

System Metrics

• provides an overview of system performance over time in metrics.csv
• measures CPU, memory, disk and network usage, temperature, etc.
• get notified when system metrics exceed configured thresholds:

Configuring Alerts

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

Speedtest

• keep a record of your internet performance over time
• currently does not perform automated runs

Network

The network widget is best used on machines with continuous uptime. Two options:

• (a) using a ddclient-style log, or
• (b) use the built-in chirper

Reminders

• facilitated by Apprise URLs (see below).
• ping yourself for system chores, key changes, etc.

Summary of Widget Features

Widget	Chart	Filters	Snapshot	Recording	Editing	Federation Merge	Notify
S. Metrics	Y	-	Y(tiles)	Y	Y(tiles)	chart	Y(alert)
Network	Y(pips)	Y(outages)	Y(tiles)	Y	N	interleave	Y(alert)
Speedtest	Y	-	-	N	-	chart	N
Services	-	Y	Y(cards)	N	Y	interleave	N
Reminders	-	Y	-	-	Y	interleave	Y
Wiki	Y	-	-	-	Y	continuous	-

[!NOTE] Key Y = supported | N = planned / potential feature | - = not applicable

General Features

Editing

• built-in Markdown editor and previewer
• configure new reminders and services directly through the web interface
• Web UI configuration seamlessly updates the YAML config file or downstream snippets

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

Federation

Yes, you can even federate multiple instances of monitorat:

• compare and plot metrics data across multiple machines
• see service statuses for your entire homelab/network from a central node
• especially useful for filtering and sorting events network-wide

[!NOTE] To simultaneously use federation of remotes AND local monitoring, you must setup a client monitorat instance and a separate monitorat server to federate locals and remotes in the same pane.

Privacy

The privacy mask helps share your setup online without exposing personal information.

privacy:
  replacements:
    my-site.org: example.com
    replace-me: with-this
    ...
  mask_ips: true

Running monitorat config will print the runtime config with these masks applied as well.

---

Development

• contributing
• changelog
• roadmap

License

GPLv3