Skip to content
Back to search

overlook

Your whole homelab on one page, laid out for you.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bnlqn--overlook/badge.svg)](/listings/bnlqn--overlook)

HTML

<a href="/listings/bnlqn--overlook"><img src="/api/listings/bnlqn--overlook/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Overlook is one container. Give it a folder of its own for its config, beside a `compose.yaml`:

overlook/
compose.yaml
# compose.yaml
services:
  overlook:
    image: ghcr.io/bnlqn/overlook:0.8
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./overlook:/etc/overlook:ro # the config and its keys, read-only: Overlook writes nothing
    environment:
      TZ: Europe/Brussels           # when today starts
    read_only: true                 # Overlook writes nothing,
    cap_drop: [ALL]                 # needs no Linux capability,
    security_opt: ["no-new-privileges:true"] # and can gain none

Then `docker compose up -d`, and open port 8080 of that host. With no config yet, Overlook shows its setup page. It asks first for the code Overlook wrote in its log as it started, which `docker compose logs overlook` shows, so that only someone who can read the log can set it up. Then pick the tools your homelab runs, give each its address and key, and try it. From the sources that answered, the setup page puts together two files, `overlook.yaml` and the `.env` that holds their keys. Save both in `overlook/`. Browsers drop the dot from a file's name as they save it, so `.env` downloads as `env`: rename it `.env`. Then `docker compose restart`, and the setup page, still open, turns into the page. A source that didn't answer its try says what to do about it, such as for a certificate Overlook doesn't trust. The log says which sources Overlook reads, and the page names any that didn't answer.

The two files look like this, and you can write them yourself instead:

# overlook/overlook.yaml
sources:
  gatus:
    - url: http://gatus.example.com:8080
  proxmox:
    - url: https://pve.example.com:8006
      token: overlook@pve!overlook
      secret: ${PROXMOX_SECRET}       # from .env
      ca: /etc/overlook/pve-root-ca.pem # copied into overlook/

apps:
  - name: Photos
    url: https://photos.example.com
    icon: immich.svg
    check: Photos
# overlook/.env: the keys
PROXMOX_SECRET=00000000-0000-0000-0000-000000000000

- **Keys come from `.env`**, beside the config, or from Overlook's environment, which wins. A `${VAR}` anywhere in the config is read from either, so the config holds no secret and can be shared or kept in git, while `.env` stays out of it. A `${VAR}` set in neither stops Overlook, and says which, and whether there is a `.env` beside the config at all. `.env` holds a `NAME=value` a line, the value all that follows the first `=`, with no quotes taken off, so a key holding `#` or a quote stays whole; a line that starts with `#` is a comment. - **The config is mounted read-only**, at `/etc/overlook`, with a CA file or your own icons beside it. The image runs as uid 65532, so the folder and its files must be readable by others, as they are by default. To keep `.env` from everyone else on the host, give it to that user: `sudo chown 65532 overlook/.env && sudo chmod 600 overlook/.env`. - **The setup page is there only while there is no `overlook.yaml`.** A config that is there but wrong, an empty one too, stops Overlook, and says why. While the setup page is up, it reads an address only for someone who gives it the code from the log, a new one each time Overlook starts, as [SECURITY.md](SECURITY.md) says. - **`TZ`** says when today starts, for today's figures. Any zone works: the zone database is inside the binary. - **The image** is `ghcr.io/bnlqn/overlook`, for amd64 and arm64: `0.8` for the newest 0.8 release, or a version such as `0.8.0`. It holds the binary and the CA certificates it checks HTTPS sources with, and nothing else.

Without Docker, each [release](https://github.com/bnlqn/overlook/releases) has the binary for Linux on amd64 and arm64, such as for an LXC container or a Raspberry Pi:

overlook -config /etc/overlook/overlook.yaml -listen :8080

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,650 lines
  1. # Overlook
  2. [![CI](https://github.com/bnlqn/overlook/actions/workflows/ci.yml/badge.svg)](https://github.com/bnlqn/overlook/actions/workflows/ci.yml)
  3. [![Release](https://img.shields.io/github/v/release/bnlqn/overlook)](https://github.com/bnlqn/overlook/releases/latest)
  4. [![Licence](https://img.shields.io/github/license/bnlqn/overlook)](LICENSE)
  5. Your whole homelab on one page, laid out for you.
  6. [![The overview of a homelab that doesn't exist: one problem, Standby DNS down, so Network is degraded; today's figures; and each area's checks](docs/overview.png)](https://bnlqn.github.io/overlook/)
  7. What's wrong, how each area of the homelab is, and what it did today and
  8. this week, on a page that is the same for every homelab. Overlook reads
  9. the tools you already run and changes nothing. If you
  10. [turn on MCP](#agents-through-mcp), your AI agent can ask it what the page
  11. shows, and can't change anything either.
  12. [See the demo](https://bnlqn.github.io/overlook/), drawn from a homelab
  13. that doesn't exist.
  14. It reads:
  15. - **Check engines**: [Gatus](#gatus), [Uptime Kuma](#uptime-kuma),
  16. [Grafana](#grafana), [Prometheus and Alertmanager](#prometheus-and-alertmanager),
  17. [Checkmate](#checkmate)
  18. - **Servers**: [Proxmox VE](#proxmox-ve), [Beszel](#beszel),
  19. [Docker](#docker), [Portainer](#portainer), [NUT](#nut)
  20. - **Network**: [UniFi Network](#unifi-network), [AdGuard Home](#adguard-home),
  21. [Pi-hole](#pi-hole), [Nginx Proxy Manager](#nginx-proxy-manager),
  22. [Traefik](#traefik)
  23. - **Storage**: [Proxmox Backup Server](#proxmox-backup-server),
  24. [Syncthing](#syncthing), and the pools, storage and backup runs of
  25. [Proxmox VE](#proxmox-ve)
  26. - **Apps**: [Immich](#immich), [Jellyfin](#jellyfin), [Emby](#emby),
  27. [Plex, through Tautulli](#plex-through-tautulli),
  28. [Audiobookshelf](#audiobookshelf), [Radarr](#radarr),
  29. [Sonarr](#sonarr), [Prowlarr](#prowlarr), [qBittorrent](#qbittorrent),
  30. [Tdarr](#tdarr), [Seerr](#seerr), [Home Assistant](#home-assistant),
  31. [Paperless-ngx](#paperless-ngx), [Nextcloud](#nextcloud), [Gitea](#gitea),
  32. [Forgejo](#forgejo)
  33. - **Chores**: [GitHub](#github), [iCalendar to-do lists](#icalendar-to-do-list)
  34. What it can't read, and why, is under [Can't be read](#cant-be-read).
  35. ## What it shows
  36. - **What's wrong**: the problems, which are the checks your check engine
  37. alerts on, for as long as they fail. Overlook runs no check and sends no
  38. alert, so the page and your alerts always agree.
  39. - **How each area is**: Servers, Network, Storage and Apps, each up,
  40. degraded (a problem, but it still works, such as DNS with one of two
  41. resolvers down) or down, with its checks' last 30 results and a page of
  42. its own with what its sources add, such as a host's guests or a
  43. resolver's top clients.
  44. - **Today**: a figure from each source, such as guests up, DNS lookups,
  45. photos or what the UPS draws.
  46. - **This week**: each area's problems and events along the last seven days,
  47. and the list of what happened, as far as your sources remember it.
  48. - **Your apps and tools**, each a link with a dot that says whether it
  49. answers.
  50. - **The chores**: the ones on your to-do list that are due or come this
  51. week, the updates waiting for your merge or to be installed, the
  52. batteries to change, the devices waiting to be adopted, the requests
  53. waiting for your approval and the certificates to renew. You do a chore where it waits, such as
  54. marking it done on the list, never on the page, and a chore is never a
  55. problem.
  56. The page is light where your system is light, and dark otherwise, and
  57. speaks your browser's language, if it is one of those under
  58. [Translating](#translating). Its footer lets you choose either: Light or
  59. Dark, and any of its languages, which your browser keeps for your next
  60. visit. On a phone, your browser's Add to Home Screen, or Install app, puts
  61. it there as an app of its own.
  62. It reads without colour or a mouse too. In forced colours, a failed result
  63. stands taller than a passed one. A screen reader says each state
  64. that a glyph or a dot shows, and a check's last results in words, such as
  65. 28 of 30 passed and the last one failed at 14:02, which the keyboard shows
  66. on each row it reaches.
  67. ## What it never does
  68. - **It never changes anything.** Overlook sends a source only GET requests,
  69. and a login where a source offers no other way in, which changes nothing
  70. but a session; it sends NUT only LIST VAR, which reads. The client it
  71. reads with refuses every other request. Some keys it holds could do
  72. anything (AdGuard Home has no read-only users, and Radarr's and Sonarr's
  73. keys are admin keys), and this is what keeps them harmless. Tautulli
  74. changes things on GET too, and Gitea and Forgejo for a few paths, so
  75. their adapters send only the commands and paths that read, from a list
  76. their tests check (ADR 0011).
  77. - **It never runs a check or sends an alert.** Your check engine does both.
  78. - **It remembers nothing.** No database and no volume: it reads every
  79. source when the page asks, at most every 30 seconds, so an Overlook
  80. nobody looks at sends nothing into your homelab. What happened this week
  81. is what your sources remember.
  82. - **It never sends a key to the browser.** The server reads every source
  83. and gives the page a snapshot of what it read, never a key or a source's
  84. own answer, and gives an agent no more, if you [turn MCP on](#agents-through-mcp).
  85. - **It never asks where to put things.** The page is fixed: your config
  86. says which sources fill it, never where anything goes. There are no
  87. widgets to arrange.
  88. - **It never calls anywhere you didn't name.** No telemetry and no update
  89. check; the page's fonts, icons and manifest come from Overlook itself.
  90. ## Quick start
  91. Overlook is one container. Give it a folder of its own for its config,
  92. beside a `compose.yaml`:
  93. ```
  94. overlook/
  95. compose.yaml
  96. ```
  97. ```yaml
  98. # compose.yaml
  99. services:
  100. overlook:
  101. image: ghcr.io/bnlqn/overlook:0.8
  102. restart: unless-stopped
  103. ports:
  104. - "8080:8080"
  105. volumes:
  106. - ./overlook:/etc/overlook:ro # the config and its keys, read-only: Overlook writes nothing
  107. environment:
  108. TZ: Europe/Brussels # when today starts
  109. read_only: true # Overlook writes nothing,
  110. cap_drop: [ALL] # needs no Linux capability,
  111. security_opt: ["no-new-privileges:true"] # and can gain none
  112. ```
  113. Then `docker compose up -d`, and open port 8080 of that host. With no
  114. config yet, Overlook shows its setup page. It asks first for the code
  115. Overlook wrote in its log as it started, which
  116. `docker compose logs overlook` shows, so that only someone who can read
  117. the log can set it up. Then pick the tools your homelab runs, give each
  118. its address and key, and try it. From the sources that
  119. answered, the setup page puts together two files, `overlook.yaml` and the
  120. `.env` that holds their keys. Save both in `overlook/`. Browsers drop the
  121. dot from a file's name as they save it, so `.env` downloads as `env`:
  122. rename it `.env`. Then `docker compose restart`, and the setup page, still
  123. open, turns into the page. A source that didn't answer its try says what
  124. to do about it, such as for a certificate Overlook doesn't trust. The log
  125. says which sources Overlook reads, and the page names any that didn't
  126. answer.
  127. The two files look like this, and you can write them yourself instead:
  128. ```yaml
  129. # overlook/overlook.yaml
  130. sources:
  131. gatus:
  132. - url: http://gatus.example.com:8080
  133. proxmox:
  134. - url: https://pve.example.com:8006
  135. token: overlook@pve!overlook
  136. secret: ${PROXMOX_SECRET} # from .env
  137. ca: /etc/overlook/pve-root-ca.pem # copied into overlook/
  138. apps:
  139. - name: Photos
  140. url: https://photos.example.com
  141. icon: immich.svg
  142. check: Photos
  143. ```
  144. ```sh
  145. # overlook/.env: the keys
  146. PROXMOX_SECRET=00000000-0000-0000-0000-000000000000
  147. ```
  148. - **Keys come from `.env`**, beside the config, or from Overlook's
  149. environment, which wins. A `${VAR}` anywhere in the config is read from
  150. either, so the config holds no secret and can be shared or kept in git,
  151. while `.env` stays out of it. A `${VAR}` set in neither stops Overlook,
  152. and says which, and whether there is a `.env` beside the config at all.
  153. `.env` holds a `NAME=value` a line, the value all that follows the first
  154. `=`, with no quotes taken off, so a key holding `#` or a quote stays
  155. whole; a line that starts with `#` is a comment.
  156. - **The config is mounted read-only**, at `/etc/overlook`, with a CA file or
  157. your own icons beside it. The image runs as uid 65532, so the folder and
  158. its files must be readable by others, as they are by default. To keep
  159. `.env` from everyone else on the host, give it to that user:
  160. `sudo chown 65532 overlook/.env && sudo chmod 600 overlook/.env`.
  161. - **The setup page is there only while there is no `overlook.yaml`.** A
  162. config that is there but wrong, an empty one too, stops Overlook, and
  163. says why. While the setup page is up, it reads an address only for
  164. someone who gives it the code from the log, a new one each time Overlook
  165. starts, as [SECURITY.md](SECURITY.md) says.
  166. - **`TZ`** says when today starts, for today's figures. Any zone works: the
  167. zone database is inside the binary.
  168. - **The image** is `ghcr.io/bnlqn/overlook`, for amd64 and arm64: `0.8` for
  169. the newest 0.8 release, or a version such as `0.8.0`. It holds the
  170. binary and the CA certificates it checks HTTPS sources with, and nothing
  171. else.
  172. Without Docker, each [release](https://github.com/bnlqn/overlook/releases)
  173. has the binary for Linux on amd64 and arm64, such as for an LXC container
  174. or a Raspberry Pi:
  175. ```bash
  176. overlook -config /etc/overlook/overlook.yaml -listen :8080
  177. ```
  178. It reads `.env` beside the config there too, and shows the setup page until
  179. the config exists, with the code it asks for in the log, on standard error.
  180. On Unraid, install Overlook from the Apps tab, where
  181. [its listing](https://ca.unraid.net/apps/overlook-0zkg6r11kddp7t) is:
  182. search for Overlook, and apply its template. Its config folder is
  183. `/mnt/user/appdata/overlook`, it runs locked down as above, and Unraid
  184. gives it `TZ` itself. Its WebUI opens the setup page, which says where
  185. Unraid shows the code from the log, and how to save the two files there.
  186. To link the Unraid server itself in the sidebar, as a tool, give it
  187. `icon: unraid.svg`, which Overlook ships.
  188. On Home Assistant OS, Overlook installs as an app, which Home Assistant
  189. called an add-on until 2026, and opens in its sidebar: in Settings, Apps,
  190. App store, add `https://github.com/bnlqn/overlook` to its repositories,
  191. install Overlook, and open it from the sidebar, which shows the setup page:
  192. the code it asks for is on the app's Log tab.
  193. Its config folder is the one Home Assistant gives it in `app_configs`,
  194. mounted read-only, and Home Assistant gives it `TZ` itself.
  195. [The app's documentation](homeassistant/DOCS.md), on its Documentation tab
  196. too, says how to save the two files there, and how to open Overlook outside
  197. the sidebar, such as for MCP.
  198. ## Configuring
  199. [`overlook.example.yaml`](overlook.example.yaml) shows every source with
  200. comments. Overlook reads the config once, at start, and refuses a key it
  201. doesn't know, so a typo stops it rather than going unnoticed.
  202. **Sources.** Under `sources:`, each adapter has a list, so two AdGuard Home
  203. resolvers are two entries under `adguard:`. Each source has a `name`, which
  204. the page uses. Each adapter gives one, such as Gatus, and two sources can't
  205. share one, so two of one adapter need names of their own. With two of one
  206. adapter, the page names each one's sections, figures and events, and adds up what
  207. adds up, such as two Proxmox hosts' guests, split by source.
  208. What each adapter reads, its config and the least key it needs are under
  209. [Adapters](#adapters) below.
  210. **Areas.** The page has four, always the same: Servers, Network, Storage
  211. and Apps, and an area with nothing in it isn't shown. Each adapter puts
  212. its parts in its own area, such as Proxmox VE in Servers and AdGuard Home
  213. in Network, but stores and backup runs go in Storage whichever adapter
  214. reads them, such as Proxmox VE's ZFS pools and its nights' backups, each
  215. looking the same whatever its source. A check goes in the area its group
  216. in the check engine is named after, or the one the config gives that
  217. group, as in Gatus's `areas:`. A check in no area still counts, and its
  218. problems still show.
  219. **Apps and tools.** Apps are what the homelab hosts for the people who use
  220. it; tools are what you run it with. Both are links on the page, in the
  221. sidebar and in ⌘K:
  222. ```yaml
  223. apps:
  224. - name: Photos # the only key besides url it needs
  225. url: https://photos.example.com
  226. icon: immich.svg # a file in overlook/icons/, one Overlook ships, or a URL
  227. check: Photos # the check that lights its dot
  228. description: The family's photos
  229. color: "#ED79B5" # tints its tile
  230. tools:
  231. - name: Proxmox
  232. url: https://pve.example.com:8006
  233. icon: proxmox.svg
  234. check: Hypervisor
  235. ```
  236. A `check` is a check's name in your check engine. With two check engines
  237. that both have a check of that name, say which, as `Gatus Outside/Photos`;
  238. if you don't, the dot shows the worse of the two, and the log says so once.
  239. Overlook ships icons for a few common apps (`web/icons`); a file of the
  240. same name in `icons/` beside the config wins over one of them.
  241. **Chores** are what you do while nothing is broken: the ones you keep on a
  242. to-do list, which the [iCalendar](#icalendar-to-do-list) source reads; the
  243. updates waiting for your merge, which the [GitHub](#github),
  244. [Gitea](#gitea) and [Forgejo](#forgejo) sources read;
  245. the updates waiting to be installed, which the
  246. [Home Assistant](#home-assistant), [Nextcloud](#nextcloud) and
  247. [UniFi](#unifi-network) sources read, the batteries to change, from Home
  248. Assistant, and the devices waiting to be adopted, from UniFi; and the
  249. requests waiting for your approval, which the [Seerr](#seerr) source reads.
  250. The page lists the chores due, from their day on, and those in the coming
  251. week, by the viewer's own calendar; with none, it says which is next. With
  252. chores from more than one source, each is named by the one it waits in. You
  253. add, change and mark chores done in your to-do app or from a script, and do
  254. the others where they wait, never on the page (ADR 0010), and the page
  255. follows within 30 seconds.
  256. **MCP.** `mcp: true` lets an AI agent read what the page shows, as
  257. [Agents, through MCP](#agents-through-mcp) says. It's off until you turn
  258. it on.
  259. **Flags.** `-config` names the config (`overlook.yaml` by default), and
  260. `.env`, `icons/` and `custom.css` are read beside it; `-listen` is the address to
  261. serve the page on (`:8080`).
  262. ## Adapters
  263. Each adapter reads the sources of one program. More come by pull request from
  264. people who run them ([CONTRIBUTING.md](CONTRIBUTING.md)).
  265. ### Gatus
  266. A check engine: every check, its last results and the problems Gatus
  267. remembers. A check is a problem once it fails as many times in a row as
  268. your alerts wait for, and stops being one when it passes.
  269. ```yaml
  270. sources:
  271. gatus:
  272. - url: http://gatus:8080 # where Overlook reads Gatus
  273. link: https://status.example.com # where the page sends you, if not the same
  274. threshold: 3 # failures in a row that make a problem: as your alerts
  275. areas: # where a group not named like an area goes
  276. DNS: network
  277. Backups: storage
  278. ```
  279. **Key:** none, as Gatus's API is open unless you protect it. If yours asks
  280. for a login, as Gatus's `security.basic` does, give it as `user` and
  281. `password`: `user: overlook` and `password: ${GATUS_PASSWORD}`.
  282. **Areas:** a group named like an area, such as Servers or network, puts its
  283. checks there. `areas` says where each other group goes, and a group it
  284. doesn't name is in no area. **Threshold:** set it to your alerts'
  285. `failure-threshold` (3 unless you changed it), so a problem on the page is
  286. one your alerts announced.
  287. ### Uptime Kuma
  288. A check engine, as Gatus is: each monitor on one of its status pages, its
  289. last 30 results and the problems they remember. A monitor is a problem once
  290. Uptime Kuma calls it down, after the retries you gave it, which is when it
  291. alerts; while it retries, the page shows it failing.
  292. ```yaml
  293. sources:
  294. uptimekuma:
  295. - url: http://uptime-kuma:3001 # where Overlook reads Uptime Kuma
  296. page: homelab # the status page's slug, as in /status/homelab
  297. link: https://uptime.example.com # where the page sends you, if not the same
  298. areas: # where a group not named like an area goes
  299. DNS: network
  300. ```
  301. **Key:** none, as a status page is public: Overlook reads the monitors on the
  302. one you name, and no others. Make one for it in Status Pages, with each
  303. monitor in a group named like an area, such as Servers or Network, or one
  304. `areas` places, as Gatus's groups are. Uptime Kuma gives a monitor's results
  305. only there and over its socket.io, after a login, which Overlook doesn't
  306. speak.
  307. A status page doesn't say why a monitor failed, so the page doesn't either.
  308. Nor does it say how many retries a monitor has: the page counts them from
  309. the last time the monitor went down, in the 100 results a status page keeps,
  310. and for a monitor that hasn't gone down there, it says how many times in a
  311. row it failed, but not how many make a problem.
  312. Uptime Kuma serves a status page's results a minute at a time.
  313. Recorded from a scratch Uptime Kuma 2.5.8 with invented monitors (ADR 0008),
  314. until someone who runs one records it from theirs: the compose file and the
  315. scripts that fill and record it are in the adapter's
  316. [`testdata`](internal/adapters/uptimekuma/testdata).
  317. ### Grafana
  318. A check engine, as Gatus is: each alert rule Grafana manages, in the area
  319. its folder is named after, or the one `areas` gives, with its last 30
  320. evaluations and the problems its state history remembers this week. A rule
  321. is a problem once it fires, or while its query gives no data or an error,
  322. which Grafana alerts on too; while it's pending, the page shows it failing,
  323. and how many evaluations its pending period holds.
  324. ```yaml
  325. sources:
  326. grafana:
  327. - url: http://grafana:3000 # where Overlook reads Grafana
  328. token: ${GRAFANA_TOKEN}
  329. link: https://grafana.example.com # where the page sends you, if not the same
  330. areas: # where a folder not named like an area goes
  331. Hosts: servers
  332. ```
  333. **Key:** a service account's token, with the role **Viewer**, which reads
  334. alert rules and their history and changes nothing. In Administration, Users
  335. and access, Service accounts, add one with that role, then add it a token.
  336. Grafana keeps only when a rule's state changed, not each evaluation, so the
  337. page draws each of the last 30 from those changes at the rule group's
  338. interval. Overlook reads each rule's history with a request of its own.
  339. Alert rules kept in a Prometheus or Loki data source, rather than by Grafana
  340. itself, are left out: the [Prometheus](#prometheus-and-alertmanager) adapter
  341. reads Prometheus's own.
  342. Recorded from a scratch Grafana 13.3 with invented alert rules over its own
  343. test data (ADR 0008), until someone who runs one records it from theirs: the
  344. compose file and the scripts that fill and record it are in the adapter's
  345. [`testdata`](internal/adapters/grafana/testdata).
  346. ### Prometheus and Alertmanager
  347. A check engine, as Gatus is: each of Prometheus's alerting rules, in the
  348. area its group is named after, or the one `areas` gives, with its last 30
  349. evaluations, from the history Prometheus keeps of its alerts, and its
  350. problems this week. A rule is a problem while it fires; while it's pending,
  351. the page shows it failing, and how many evaluations its `for` holds. With
  352. Alertmanager read too, a rule all of whose alerts Alertmanager silences or
  353. inhibits isn't a problem, since Alertmanager sends no alert for it: the page
  354. shows it failing, with the silence's comment.
  355. ```yaml
  356. sources:
  357. prometheus:
  358. - url: http://prometheus:9090 # where Overlook reads Prometheus
  359. alertmanager: http://alertmanager:9093 # its Alertmanager, if any
  360. link: https://prometheus.example.com # where the page sends you, if not the same
  361. areas: # where a rule group not named like an area goes
  362. node: servers
  363. ```
  364. **Key:** none, as Prometheus's and Alertmanager's APIs are open unless you
  365. protect them. If yours ask for a login, as `basic_auth_users` in Prometheus's
  366. web config does, give it as `user` and `password`, the same for both.
  367. Overlook reads the rules, two range queries of the `ALERTS` series and
  368. Alertmanager's alerts and silences, all with GET, which change nothing.
  369. This week's problems are read to five minutes, which a week of firing
  370. alerts holds in a few thousand samples.
  371. Recorded from a scratch Prometheus 3.15 and Alertmanager 0.34 with invented
  372. alert rules over numbers of their own (ADR 0008), until someone who runs
  373. them records it from theirs: the compose file, the rules and the scripts
  374. that fill and record it are in the adapter's
  375. [`testdata`](internal/adapters/prometheus/testdata).
  376. ### Checkmate
  377. A check engine, as Gatus is: each monitor Checkmate checks, in the area its
  378. group is named after, or the one `areas` gives, with its last 30 results
  379. and the problems its incidents remember this week. A monitor is a problem
  380. once Checkmate calls it down, when enough of the last checks in its status
  381. window failed, which is when it alerts; until then, the page shows it
  382. failing, and how many failures in a row make a problem, 3 at the window's
  383. 5 checks and 60%. A hardware or Docker monitor is a problem too while
  384. Checkmate calls it breached, over a threshold you gave it: its results fail
  385. for as long, with what crossed it.
  386. ```yaml
  387. sources:
  388. checkmate:
  389. - url: http://checkmate:52345 # where Overlook reads Checkmate
  390. user: overlook@example.com # its user's email
  391. password: ${CHECKMATE_PASSWORD}
  392. link: https://checkmate.example.com # where the page sends you, if not the same
  393. areas: # where a group not named like an area goes
  394. DNS: network
  395. ```
  396. **Key:** a login, as `user` and `password`, since Checkmate has no API
  397. keys. Overlook logs in with one POST, keeps the token in memory and sends
  398. it with each GET, logging in again when Checkmate refuses it, after the 99
  399. days it lasts unless you changed `TOKEN_TTL` (ADR 0009). The least it needs
  400. is a user of its own with the role **User**, which reads every monitor and
  401. its incidents, and can pause, change or delete none. As the super admin, in
  402. your account's Team, use Add member to make one with that role.
  403. A monitor you paused is left out, as Checkmate neither checks it nor alerts
  404. on it. One in a maintenance window isn't a problem either, for the same
  405. reason: the page shows its last results from before the window, failing if
  406. it was failing then. Checkmate lists a hardware monitor with its newest
  407. check alone, so Overlook reads each one's last 30 with a request of its
  408. own. A published status page could be read without a login, but it doesn't
  409. say which group a monitor is in, so nothing would place its checks in an
  410. area.
  411. Recorded from a scratch Checkmate 3.13.1 with invented monitors, and a
  412. Capture agent 1.4.0 for its hardware monitors (ADR 0008), until someone who
  413. runs one records it from theirs: the compose file and the scripts that fill
  414. and record it are in the adapter's
  415. [`testdata`](internal/adapters/checkmate/testdata).
  416. ### GitHub
  417. The updates waiting: the open pull requests Dependabot or Renovate opened on
  418. the repositories you list. They are chores, never problems.
  419. ```yaml
  420. sources:
  421. github:
  422. - repos: [example/homelab, example/website]
  423. token: ${GITHUB_TOKEN} # only for private repositories
  424. # bots: ["dependabot[bot]", "renovate[bot]"] # whose pull requests are updates
  425. # url: https://github.example.com/api/v3 # a GitHub Enterprise Server's API
  426. ```
  427. **Key:** none for public repositories. For private ones, a
  428. [fine-grained token](https://github.com/settings/personal-access-tokens/new)
  429. with read-only access to **Pull requests** on those repositories (GitHub adds
  430. **Metadata** itself). Without one, GitHub answers 404 for a private
  431. repository.
  432. Overlook reads GitHub at most every 10 minutes, so an update can take that
  433. long to show. Without a token GitHub allows 60 requests an hour from your
  434. address, and each read is one request per repository: ten repositories hold,
  435. fewer if something else at your address reads GitHub without a token.
  436. ### iCalendar to-do list
  437. The chores you keep on a to-do list, read from the iCalendar file a CalDAV
  438. server gives for a GET, such as Radicale, Nextcloud or Baïkal. Edit the list
  439. in any app that syncs it, such as Reminders on an iPhone, Tasks.org with
  440. DAVx⁵ on Android, or Thunderbird, or from a script over CalDAV.
  441. ```yaml
  442. sources:
  443. ical:
  444. - url: https://dav.example.com/owner/chores/ # the list, as Radicale serves it
  445. user: owner # a login, if the server asks for one
  446. password: ${DAV_PASSWORD}
  447. # name: Chores # what the page calls it, if you keep more than one list
  448. ```
  449. On Nextcloud or Baïkal the `url` is the list's CalDAV address with `?export`
  450. at the end, such as
  451. `https://cloud.example.com/remote.php/dav/calendars/owner/chores/?export`.
  452. A to-do's title is the chore and its description the note. Its due date is
  453. the day it's due from, a time counting as its day, and one with no due date
  454. is due now. One marked done or cancelled leaves the page. A to-do that comes
  455. back is your app's to move on when you mark it done, and Overlook reads only
  456. the next due date.
  457. **Key:** a login that can read the list, as `user` and `password`, sent by
  458. HTTP's basic authentication, or none if the list is open. Overlook only ever
  459. sends it with GET (ADR 0001). The least it needs, on Radicale, is a user of
  460. its own with only `i` on the list, which lets it GET the list and nothing
  461. else. With Radicale's rights from a file (`[rights] type = from_file`), beside
  462. the sections that give each user their own:
  463. ```ini
  464. [overlook]
  465. user: overlook
  466. collection: owner/chores
  467. permissions: i
  468. ```
  469. Baïkal asks for Digest unless its admin page sets Basic, which Overlook needs.
  470. Recorded from Radicale; Nextcloud and Baïkal give the same iCalendar for
  471. `?export`, but haven't been recorded.
  472. ### Immich
  473. The photos, on the Apps page: what each person keeps and uploaded this week,
  474. the space they take on Immich's disk, Immich's version and whether a newer one
  475. is out, and the jobs queued. Today's figure is everyone's photos and videos,
  476. with each person's share of the room they take.
  477. ```yaml
  478. sources:
  479. immich:
  480. - url: http://immich:2283
  481. key: ${IMMICH_KEY}
  482. # name: Photos # what the page calls it, if not Immich
  483. ```
  484. **Key:** an API key made by an admin (Account Settings, API Keys), since
  485. Immich shows everyone's photos, the queues and each person's uploads only to
  486. an admin. Give it only these six read permissions:
  487. - `server.statistics`: each person's photos, videos and space
  488. - `server.storage`: the disk the photos are on
  489. - `server.about`: Immich's version
  490. - `server.versionCheck`: the newest version released
  491. - `queue.read`: the jobs queued
  492. - `adminUser.read`: what each person uploaded this week
  493. What each person uploaded needs Immich 3 or later; an older one leaves it out.
  494. ### Proxmox Backup Server
  495. One datastore, in Storage: how full it is, its nights as backup runs, and
  496. each guest's newest backup in it, with when it was made, its size, and
  497. whether it passed its check, named by its notes, which Proxmox VE fills
  498. with the guest's name. A night is the backups made one after another, so
  499. PBS says when it started and how many backups it made, but not when it
  500. ended. Today shows how many guests the last night backed up, each guest
  501. blue where it did, and the week each night's backup run. The last night is
  502. the run with the most guests in the day to the newest backup, so a guest
  503. backed up by hand after it doesn't hide it.
  504. ```yaml
  505. sources:
  506. pbs:
  507. - url: https://pbs.example.com:8007
  508. token: overlook@pbs!overlook
  509. secret: ${PBS_SECRET}
  510. datastore: backups
  511. ca: /etc/overlook/pbs.pem # PBS's own certificate, copied from the server
  512. # server_name: pbs.example.com # the name it's for, if the url uses another
  513. ```
  514. **Key:** an API token with the role **DatastoreAudit** on that datastore,
  515. which lists the backups and can't read them. A token can do no more than
  516. its user, so both get the role. On the server:
  517. ```bash
  518. proxmox-backup-manager user create overlook@pbs
  519. proxmox-backup-manager acl update /datastore/backups DatastoreAudit --auth-id overlook@pbs
  520. proxmox-backup-manager user generate-token overlook@pbs overlook
  521. proxmox-backup-manager acl update /datastore/backups DatastoreAudit --auth-id 'overlook@pbs!overlook'
  522. ```
  523. The third command prints the token's secret. The same role reads how full
  524. the datastore is.
  525. **Certificate:** PBS signs its own, for its own name. Copy
  526. `/etc/proxmox-backup/proxy.pem` from the server beside Overlook and name it
  527. as `ca`. If the `url` reaches PBS by an address its certificate doesn't
  528. name, give the name it does as `server_name`. As for Proxmox VE, there is
  529. no way to skip the check.
  530. The backups were recorded from a PBS 4, with every name and number made up.
  531. How full the datastore is was recorded from a scratch PBS 4.2.9 (ADR 0008),
  532. until someone who runs one records it from theirs: the compose file and the
  533. scripts that fill and record it are in the adapter's
  534. [`testdata`](internal/adapters/pbs/testdata).
  535. ### Syncthing
  536. One Syncthing device, in Storage: each folder, up to date with what it
  537. holds, syncing or out of sync with what it still needs, paused, or in red
  538. when items failed to sync or the folder stopped, with why; then each other
  539. device, connected or since when it isn't, and how much of what it shares it
  540. has; Syncthing's version and whether a newer one is out; and its errors, in
  541. red, until you clear them in its GUI. Each device asking to connect and
  542. each folder offered to it is a chore, from the day it asked, done where
  543. Syncthing asks you to accept or ignore it.
  544. ```yaml
  545. sources:
  546. syncthing:
  547. - url: http://syncthing:8384 # where Overlook reads its GUI
  548. key: ${SYNCTHING_KEY}
  549. link: https://sync.example.com # where the page sends you, if not the same
  550. ```
  551. **Key:** the API key, from Actions, Settings, GUI. It's the only key
  552. Syncthing has, and it can do anything, but Syncthing changes things only
  553. with POST, PUT, PATCH and DELETE, and Overlook sends it only with GET
  554. (ADR 0001). Overlook reads the folders and devices from the config, but
  555. never the whole config, which holds the GUI's password and the key.
  556. The GUI must listen where Overlook can reach it, as in Syncthing's Docker
  557. image; a Syncthing installed on its own listens on `127.0.0.1:8384` until
  558. you set its GUI's listen address to `0.0.0.0:8384`. With its GUI over HTTPS,
  559. give its certificate, `https-cert.pem` in its config folder, as `ca`, and the
  560. host's name, which it is for, as `server_name`.
  561. Syncthing's Docker image, and most distributions' packages, are built
  562. without upgrades, and refuse to say whether a newer one is out, so the page
  563. shows only the version they run. Overlook reads each folder's state and each
  564. device's completion with a request of its own.
  565. Recorded from a scratch Syncthing 2.1.7, four devices with invented folders
  566. (ADR 0008), until someone who runs it records it from theirs: the compose
  567. file and the scripts that fill and record it are in the adapter's
  568. [`testdata`](internal/adapters/syncthing/testdata).
  569. ### Proxmox VE
  570. Each host's processor, memory, uptime and version, and the guests, in
  571. Servers, with each host's processor and memory by the hour over the week
  572. Proxmox keeps, a line each. The ZFS pools and the storage go in Storage, as
  573. every source's stores do: how full each is, and each pool's health, in red
  574. when it isn't ONLINE, as is a storage Proxmox VE can't reach. So do the
  575. backup runs: each host's last run, and the week each run. A storage on a
  576. Proxmox Backup Server that Overlook reads too shows once, as that server's
  577. datastore. Today shows how many guests are up.
  578. ```yaml
  579. sources:
  580. proxmox:
  581. - url: https://pve.example.com:8006 # any host of a cluster reads all of it
  582. token: overlook@pve!overlook
  583. secret: ${PROXMOX_SECRET}
  584. ca: /etc/overlook/pve-root-ca.pem # Proxmox's own CA, copied from the host
  585. ```
  586. **Key:** an API token of a user with the role **PVEAuditor**, which reads
  587. everything and changes nothing. On the host:
  588. ```bash
  589. pveum user add overlook@pve
  590. pveum acl modify / --users overlook@pve --roles PVEAuditor
  591. pveum user token add overlook@pve overlook --privsep 0
  592. ```
  593. The last command prints the token's secret. The user has no password, so
  594. the token is the only way in, and it can do no more than the user.
  595. **Certificate:** Proxmox signs its own. Copy `/etc/pve/pve-root-ca.pem` from
  596. the host beside Overlook and name it as `ca`: Overlook then trusts that CA
  597. alone for this source. There is no way to skip the check, since a key sent
  598. to whoever answers in Proxmox's place is given away. A host with a
  599. certificate from a public CA, such as Let's Encrypt, needs no `ca`.
  600. ### Radarr
  601. The films on disk and the room they take, the films added this week, what
  602. Radarr is downloading and warns about, and the films out to stream or on
  603. disc in the next seven days. Its home area is Apps. With Sonarr read too, the
  604. films and shows share one tile in Today, the library, split by the room each
  605. takes.
  606. ```yaml
  607. sources:
  608. radarr:
  609. - url: http://radarr:7878 # where Overlook reads Radarr
  610. key: ${RADARR_KEY}
  611. name: Radarr # if you run more than one, tell them apart
  612. ```
  613. **Key:** Radarr's API key, from Settings, General. It's the only key Radarr
  614. has, and it can do anything, but Overlook sends it only with GET requests,
  615. which change nothing (ADR 0001).
  616. Radarr answers with every film at once, so Overlook reads the films at most
  617. every 10 minutes, and a film can take that long to count. The rest is read
  618. with every snapshot.
  619. ### Sonarr
  620. The shows and episodes on disk and the room they take, the episodes imported
  621. this week, what Sonarr is downloading and warns about, and the episodes that
  622. air in the next seven days. Its home area is Apps. With Radarr read too, its
  623. shows share the library's tile with the films.
  624. ```yaml
  625. sources:
  626. sonarr:
  627. - url: http://sonarr:8989 # where Overlook reads Sonarr
  628. key: ${SONARR_KEY}
  629. name: Sonarr # if you run more than one, tell them apart
  630. ```
  631. **Key:** Sonarr's API key, from Settings, General. Like Radarr's, it's the
  632. only key and it can do anything, and Overlook sends it only with GET requests
  633. (ADR 0001).
  634. The shows are read at most every 10 minutes, as Radarr's films are.
  635. ### NUT
  636. A UPS, read from NUT's upsd over NUT's own protocol. Servers shows whether it
  637. runs on mains or on its battery, its model and the voltage it's fed, the
  638. battery's charge and how long it would last, and what its load draws; the
  639. overview shows the draw and the battery.
  640. ```yaml
  641. sources:
  642. nut:
  643. - host: nut.example.com # upsd, as host or host:port (3493 unless you say)
  644. ups: ups # the UPS's name in upsd, as in its ups.conf
  645. ```
  646. upsd needs no login for this: Overlook sends only `LIST VAR` for the UPS
  647. named, and has no code to send any other command.
  648. upsd must listen where Overlook can reach it, which by default it doesn't:
  649. set `MODE=netserver` in `nut.conf`, add a `LISTEN` line for the address
  650. Overlook reaches to `upsd.conf` (such as `LISTEN 192.0.2.13 3493`), and let
  651. Overlook through any firewall to that port. The readings cross the network
  652. unencrypted, as upsd sends them without TLS.
  653. ### UniFi Network
  654. Each UniFi OS console, such as a Cloud Gateway, a Dream Machine or UniFi OS
  655. Server, and every site on it, in Network. First the internet: each WAN, how
  656. long it has been up, how much of the last day it answered and how fast, or
  657. since when it's down, and the last speed test. A WAN down since the gateway
  658. started, as a spare port with nothing in it is, is grey while another is
  659. up; one that drops is red. Then each device, the gateway, switches and
  660. access points: how long it has been up and how busy its processor and how
  661. full its memory are, or its state, offline in red and interrupted in orange.
  662. Today shows the clients connected, wired, wireless and on the VPN, every
  663. console's added up, in orange while a device or a WAN is down. A device
  664. offline isn't a problem, since Overlook runs no check: give it a check in
  665. your check engine to make it one. The chores are each device whose firmware
  666. waits, a gateway's being UniFi OS itself, each device waiting to be adopted,
  667. and the Network application's update.
  668. ```yaml
  669. sources:
  670. unifi:
  671. - url: https://unifi.example.com
  672. key: ${UNIFI_KEY}
  673. ca: /etc/overlook/unifi.pem # the console's own certificate
  674. server_name: unifi.local # the name it's for
  675. ```
  676. **Key:** an API key, from the Network application's **Integrations**:
  677. **Create New API Key**, with **Never Expires**. UniFi has no read-only key,
  678. so it could change anything on the console, every site and device; what
  679. keeps it harmless is that Overlook only ever sends GET (ADR 0001). It needs
  680. UniFi OS and Network 10.0 or later.
  681. **Certificate:** the console signs its own, for `unifi.local`, and Overlook
  682. never reads a source it can't check. Save it with
  683. `openssl s_client -connect unifi.example.com:443 </dev/null | openssl x509 >unifi.pem`,
  684. give it as `ca` and name `unifi.local` as `server_name`. When the console
  685. makes a new one, every two years or so, save it again. With a certificate
  686. of your own on the console, you need neither.
  687. **Two reads nothing documents.** UniFi's documented API says nothing of the
  688. WANs or of the Network application's update, so Overlook reads them from
  689. the API before it, with the same key and a GET too. Ubiquiti changes that
  690. one without warning: when a change breaks a read, the Internet section or
  691. that chore goes missing, and the rest stays, until the adapter is recorded
  692. again. UniFi's history isn't read: its events come only from a POST, and
  693. its traffic by the hour from a read that Network 11 has only just moved.
  694. Recorded from the maintainer's Cloud Gateway Fiber, on UniFi OS 5.1.34 with
  695. Network 10.6.109, with every name, ID and MAC address made up; its
  696. [`record.sh`](internal/adapters/unifi/testdata/record.sh) records yours.
  697. ### AdGuard Home
  698. Each resolver is its own source. Today's lookups and blocks show on the
  699. Overview, every resolver's added up, hour by hour. The Network page charts
  700. them by the hour over the hours every resolver keeps, added up too, then shows
  701. each one: whether it blocks, its lookups, blocks and upstreams, how fast it
  702. answers and its version, and its top clients, domains and blocked domains,
  703. over the interval its statistics keep. The Overview's lookups turn orange
  704. while a resolver doesn't block.
  705. ```yaml
  706. sources:
  707. adguard:
  708. - name: Primary DNS
  709. url: http://dns1.example.com
  710. user: overlook
  711. password: ${ADGUARD_PASSWORD}
  712. - name: Standby DNS
  713. url: http://dns2.example.com
  714. user: overlook
  715. password: ${ADGUARD_PASSWORD}
  716. ```
  717. **Key:** a login, as `user` and `password`. AdGuard Home has no
  718. read-only users, so that login could change anything; what keeps it
  719. harmless is that Overlook only ever sends GET (ADR 0001). Give Overlook a
  720. user of its own: add it under `users:` in `AdGuardHome.yaml`, with its
  721. password hashed by `htpasswd -B -C 10 -n -b overlook <password>`, and
  722. restart AdGuard Home.
  723. **Today** starts at midnight in Overlook's time zone: set `TZ`, such as
  724. `TZ=Europe/Brussels`, in its container. AdGuard Home keeps statistics by
  725. the hour for an interval of up to 7 days; over a longer one it keeps them
  726. by the day, in UTC, and the Overview shows no figure for it.
  727. ### Pi-hole
  728. A resolver, as AdGuard Home is: each one is its own source, and its lookups
  729. add up with every other resolver's, AdGuard Home's too, on the Overview and
  730. in the Network page's chart, hour by hour over the last day, which is all
  731. Pi-hole keeps in memory, so beside a resolver that keeps a week, the chart
  732. shows the day they both have. Then each one, as any resolver: whether it
  733. blocks, or is paused and until when, its lookups, blocks and upstreams; then
  734. its blocklists and when they were last updated, what it warns about, such
  735. as a client it rate-limits, its version and whether a newer one is out; and
  736. its top clients, domains and blocked domains.
  737. ```yaml
  738. sources:
  739. pihole:
  740. - name: Kids' DNS
  741. url: http://pihole.example.com
  742. password: ${PIHOLE_PASSWORD}
  743. ```
  744. **Key:** an app password, from Settings, Web interface / API, in expert
  745. mode: **Configure app password**. Pi-hole gives a session only for a login,
  746. so Overlook logs in with one POST, keeps the session in memory and sends it
  747. with each GET, logging in again only when Pi-hole forgets it (ADR 0009). An
  748. app password logs in without the second factor, if you set one, and Pi-hole
  749. has no read-only one, so it could change anything; what keeps it harmless is
  750. that Overlook sends nothing else. With no password set in Pi-hole, leave
  751. `password` out. Each Overlook keeps one of the sessions Pi-hole allows, 16
  752. unless you changed `webserver.api.max_sessions`.
  753. Recorded from a scratch Pi-hole 2026.10 with invented clients and domains
  754. (ADR 0008), until someone who runs one records it from theirs: the compose
  755. file and the scripts that fill and record it are in the adapter's
  756. [`testdata`](internal/adapters/pihole/testdata).
  757. ### Nginx Proxy Manager
  758. One Nginx Proxy Manager, in Network: each proxy host, redirection, 404 host
  759. and stream, with where it sends what it receives, grey while it's disabled,
  760. and in red when nginx refused its config, with what nginx said, since
  761. Nginx Proxy Manager then serves nothing for it; and its version and whether
  762. a newer one is out. Then the certificates they serve, the one that ends
  763. first first, in orange within 30 days of its end, and red once it has
  764. ended. A certificate within 30 days is a chore too, done in Nginx Proxy
  765. Manager's Certificates: one from Let's Encrypt is renewed from 30 days
  766. before its end, so one still within them isn't renewing.
  767. ```yaml
  768. sources:
  769. npm:
  770. - url: http://npm:81 # where Overlook reads its admin
  771. user: overlook@example.com # its user's email
  772. password: ${NPM_PASSWORD}
  773. link: https://npm.example.com # where the page sends you, if not the same
  774. ```
  775. **Key:** a login, as `user` and `password`, since Nginx Proxy Manager has
  776. no API keys. Overlook logs in with one POST, keeps the token in memory and
  777. sends it with each GET, logging in again once it lapses, after a day
  778. (ADR 0009). The least it needs is a user of its own: in Users, add one
  779. without Administrator, then, in its Permissions, give it All Items under
  780. Item Visibility, so that it sees the hosts you made, and View Only on Proxy
  781. Hosts, Redirection Hosts, 404 Hosts and Streams. Leave Certificates and
  782. Access Lists hidden: each host brings the name and end of the certificate
  783. it serves, while Nginx Proxy Manager's list of certificates gives whoever
  784. may view it the private key of every certificate you uploaded. Overlook
  785. can't answer a second factor, so give its user none.
  786. Nginx Proxy Manager doesn't check whether what a host sends to answers, so
  787. a host pointing at nothing looks like any other: your check engine says
  788. whether it answers. A stream pointing at a name that doesn't resolve is
  789. refused by nginx, and shows in red. A certificate no host serves is left
  790. out. Nginx Proxy Manager asks GitHub whether a newer one is out, and when it
  791. can't, the page shows no version.
  792. Recorded from a scratch Nginx Proxy Manager 2.16.0 with invented hosts and
  793. self-signed certificates (ADR 0008), until someone who runs one records it
  794. from theirs: the compose file and the scripts that fill and record it are
  795. in the adapter's [`testdata`](internal/adapters/npm/testdata).
  796. ### Traefik
  797. One Traefik, in Network, read from its API. First how many HTTP routers,
  798. services and middlewares it has, each count in red while one of them is in
  799. error and in orange while Traefik warns about one; then each it holds in
  800. error or warns about, with what Traefik says of it, such as a middleware
  801. that doesn't exist; then each service whose servers it checks, actively or
  802. by the requests it sends, with its servers all up, or in red with the ones
  803. down. Then its certificates, by when each expires, sooner first, in orange
  804. within 30 days and in red once expired. A certificate within 30 days is a
  805. chore, from the day it came within them. Traefik renews a 90-day
  806. certificate from Let's Encrypt, as theirs are by default, 30 days before it
  807. expires, so that one is a chore only once its renewal fails; one you gave
  808. Traefik yourself is yours to renew.
  809. ```yaml
  810. sources:
  811. traefik:
  812. - url: https://traefik.example.com # where Overlook reads its API, under /api
  813. user: overlook # the login of a basicAuth middleware in front of it, if there is one
  814. password: ${TRAEFIK_PASSWORD}
  815. ```
  816. **Key:** none of Traefik's own. Its API only reads, so Overlook reads it as
  817. you serve it: open, as `api.insecure` serves it on port 8080, or through the
  818. router you gave `api@internal`, behind a basicAuth middleware, whose login
  819. you give as `user` and `password`. Give Overlook a user of its own among
  820. that middleware's `users`.
  821. It needs Traefik 3.7 or later, whose API added the certificates. It reads
  822. the HTTP routers, services and middlewares, not the TCP or UDP ones, each
  823. list whole in one request.
  824. Recorded from a scratch Traefik 3.7.17 with invented routers and
  825. self-signed certificates (ADR 0008), until someone who runs it records it
  826. from theirs: the compose file, its routers and the scripts that fill and
  827. record it are in the adapter's
  828. [`testdata`](internal/adapters/traefik/testdata).
  829. ### Beszel
  830. Each system Beszel's agents report on, as a host, in Servers: how long it
  831. has been up, its threads and load, and how busy its processor and how full
  832. its memory and disk are, or since when it's down. Its processor and memory
  833. by the hour, over the week Beszel keeps, are a line each on the same charts
  834. as any other source's hosts, such as Proxmox's. Today shows the hosts up,
  835. every hub's added up.
  836. ```yaml
  837. sources:
  838. beszel:
  839. - url: http://beszel:8090 # where Overlook reads the hub
  840. user: overlook@example.com # its user's email
  841. password: ${BESZEL_PASSWORD}
  842. ```
  843. **Key:** a login, as `user` and `password`, since Beszel has no API keys.
  844. Overlook logs in with one POST, keeps the session in memory and sends it
  845. with each GET, logging in again when Beszel forgets it (ADR 0009). The least
  846. it needs is a user of its own with the role **readonly**, which can change
  847. nothing, nor read the agents' keys. As a superuser, in the hub's admin page
  848. at `/_/`, add the user to the `users` collection with `role` set to
  849. `readonly`, then add it to the `users` of each system to show, or set
  850. `SHARE_ALL_SYSTEMS=true` on the hub so that every user sees every system.
  851. ### Docker
  852. Each container a Docker engine runs, in Servers: its image, and whether it
  853. runs, those that exited with an error, restart or fail their health check
  854. in red or orange, and one that exited cleanly, as a job does when it's
  855. done, in grey. Today shows the containers running, every engine's added up.
  856. ```yaml
  857. sources:
  858. docker:
  859. - url: http://socket-proxy:2375 # Docker's API, through a socket proxy
  860. name: Media # if you run more than one engine, tell them apart
  861. ```
  862. **Key:** none, as Docker's API has no login and no read-only access:
  863. whoever reaches its socket is root on the host, even through a socket
  864. mounted read-only. So Overlook reads it only through a socket proxy that
  865. lets the containers' reads through and refuses the rest, over HTTP: it has
  866. no way to read Docker's socket itself, nor Docker's API over TLS. With
  867. [linuxserver's socket proxy](https://docs.linuxserver.io/images/docker-socket-proxy/),
  868. beside the containers on each host:
  869. ```yaml
  870. services:
  871. socket-proxy:
  872. image: lscr.io/linuxserver/socket-proxy:3.4.7
  873. environment:
  874. CONTAINERS: "1" # the containers' reads; every write stays refused
  875. volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"]
  876. read_only: true
  877. tmpfs: [/run]
  878. ports: ["2375:2375"] # where Overlook reaches it: keep it from anyone else
  879. ```
  880. Overlook reads only the list of containers, never a container's own
  881. details, which hold its environment and so its keys.
  882. ### Portainer
  883. Each environment Portainer manages, in Servers: down in red, with when
  884. Portainer last saw it, or its containers running, of all, in orange while
  885. one fails its health check, and its stacks, whoever started them; then
  886. Portainer's version, and whether a newer one is out. Today's containers add
  887. up with every Docker engine's, and those of an environment that's down
  888. don't count.
  889. ```yaml
  890. sources:
  891. portainer:
  892. - url: https://portainer:9443 # where Overlook reads Portainer
  893. key: ${PORTAINER_KEY}
  894. ca: /etc/overlook/portainer.pem # Portainer's own certificate
  895. server_name: localhost # the name it's for
  896. ```
  897. **Key:** an access token of a user of Overlook's own. As an administrator,
  898. add the user in Users, not as an administrator, and give it only the
  899. environments to show, in each one's Manage access; then log in as it, and
  900. add the token in My account, Access tokens. The token never expires.
  901. Portainer CE has no role that only reads, so that user could change
  902. containers in those environments; what keeps it harmless is that Overlook
  903. sends only GET requests (ADR 0001). On Portainer Business, give it the
  904. role **Read-only user**. Overlook reads only the list of environments and
  905. Portainer's version, never a container through Portainer, whose answer
  906. holds its environment and so its keys.
  907. **Certificate:** Portainer signs its own, on port 9443, for `localhost`.
  908. Save it with
  909. `openssl s_client -connect portainer.example.com:9443 </dev/null | openssl x509 >portainer.pem`,
  910. give it as `ca` and name `localhost` as `server_name`. With a certificate of
  911. your own, or Portainer over HTTP on port 9000, you need neither.
  912. The counts come from the snapshot Portainer takes of each environment,
  913. every five minutes unless you changed it in Settings, so a container can
  914. take that long to count. An Edge agent's environment is up while the agent
  915. calls Portainer. A Kubernetes environment shows only whether it's up.
  916. Recorded from a scratch Portainer CE 2.45.3 managing two Docker engines with
  917. invented containers (ADR 0008), until someone who runs one records it from
  918. theirs: the compose file and the scripts that fill and record it are in the
  919. adapter's [`testdata`](internal/adapters/portainer/testdata).
  920. ### Prowlarr
  921. Each indexer, on the Apps page: whether it's enabled, those Prowlarr leaves
  922. out because they fail, in red with since when, and what each was asked and
  923. grabbed this week; and what Prowlarr warns about.
  924. ```yaml
  925. sources:
  926. prowlarr:
  927. - url: http://prowlarr:9696 # where Overlook reads Prowlarr
  928. key: ${PROWLARR_KEY}
  929. ```
  930. **Key:** Prowlarr's API key, from Settings, General. Like Radarr's, it's the
  931. only key and it can do anything, even read each indexer's own key, and
  932. Overlook sends it only with GET requests (ADR 0001).
  933. ### qBittorrent
  934. The torrents, on the Apps page: how many download and seed and how fast,
  935. the room left on qBittorrent's disk, whether peers can reach it, and each
  936. torrent in error, with where it's saved. Today shows the torrents
  937. downloading, every qBittorrent's added up.
  938. ```yaml
  939. sources:
  940. qbittorrent:
  941. - url: http://qbittorrent:8080 # where Overlook reads its web UI
  942. key: ${QBITTORRENT_KEY}
  943. ```
  944. **Key:** from qBittorrent 5.2, an API key, from Options, WebUI. It can do
  945. anything the web UI can, and Overlook sends it only with GET requests
  946. (ADR 0001). Before 5.2 there are no keys: give the web UI's login as `user`
  947. and `password` instead, and Overlook logs in with one POST, keeps the
  948. session in memory and sends it with each GET, logging in again only when
  949. qBittorrent forgets it (ADR 0009). A wrong password is tried once a read,
  950. so qBittorrent bans Overlook's address after five, for an hour unless you
  951. changed it. With neither, qBittorrent must let Overlook in without a login,
  952. as its bypass for whitelisted subnets does for Overlook's address.
  953. The list of every torrent, which gives the counts and the room left, is
  954. megabytes for a thousand torrents, so Overlook reads it at most every 10
  955. minutes. The speeds, the connection and the torrents in error are read with
  956. every snapshot.
  957. ### Tdarr
  958. The files Tdarr is transcoding or health-checking now, on the Apps page, each
  959. with how far along it is, how fast and how long it has left, and how many
  960. files wait. Tdarr adds a section only while a node is working on something
  961. or files wait, and Today shows the files in work only while there are some:
  962. with nothing to do, Tdarr has nothing to add and the page leaves it out. With
  963. files waiting and nothing in work, the section names each node that is
  964. paused.
  965. ```yaml
  966. sources:
  967. tdarr:
  968. - url: http://tdarr:8265 # where Overlook reads Tdarr's server
  969. # key: ${TDARR_KEY} # only if you have set an API key
  970. ```
  971. **Key:** none unless you set one, under Tools, Options, on Tdarr's server,
  972. and then Overlook sends it as `X-Api-Key` with every GET. Tdarr's totals of
  973. what it has done answer only to a POST, which Overlook doesn't send (ADR
  974. 0001), so they aren't shown.
  975. ### Jellyfin
  976. The films, shows and music, on the Apps page: what each person plays now
  977. and how, as it is, transcoded or paused; how many films, shows, albums and
  978. books there are; the room left on each disk the libraries are on; the failed
  979. logins of the last day; and each task whose last run failed, such as a
  980. library's scan, in red with why. Today shows the plays since midnight, hour
  981. by hour, every Jellyfin's added up.
  982. ```yaml
  983. sources:
  984. jellyfin:
  985. - url: http://jellyfin:8096 # where Overlook reads Jellyfin
  986. key: ${JELLYFIN_KEY}
  987. ```
  988. **Key:** an API key, from the dashboard's API Keys. It's the only kind
  989. Jellyfin makes, and it can do anything an administrator can, but Overlook
  990. sends it only with GET requests, which change nothing (ADR 0001).
  991. Recorded from a scratch Jellyfin 12.4 filled with invented films and people
  992. (ADR 0008), until someone who runs one records it from theirs: the compose
  993. file and the scripts that fill and record it are in the adapter's
  994. [`testdata`](internal/adapters/jellyfin/testdata).
  995. ### Emby
  996. The films, shows and music, on the Apps page: what each person plays now
  997. and how, as it is, transcoded or paused; how many films, shows, albums and
  998. books there are; the failed logins of the last day; and each task whose last
  999. run failed, such as a library's scan, in red with why. Today shows the plays
  1000. since midnight, hour by hour, every media server's added up.
  1001. ```yaml
  1002. sources:
  1003. emby:
  1004. - url: http://emby:8096 # where Overlook reads Emby
  1005. key: ${EMBY_KEY}
  1006. ```
  1007. **Key:** an API key, from the dashboard's Advanced section, API Keys. It's
  1008. the only kind Emby makes, and it can do anything an administrator can, but
  1009. Overlook sends it only with GET requests, which change nothing (ADR 0001).
  1010. Recorded from a scratch Emby 4.10 filled with invented films and people
  1011. (ADR 0008): the compose file and the scripts that fill and record it are in
  1012. the adapter's [`testdata`](internal/adapters/emby/testdata).
  1013. ### Plex, through Tautulli
  1014. Plex, on the Apps page, as Tautulli watches it: what each person plays now
  1015. and how, as it is, transcoded or paused, and the bandwidth it takes, of it
  1016. to remote players; each library, by what it holds; whether a newer Plex is
  1017. out, when Tautulli knows; and, in red, a Plex server Tautulli can't reach.
  1018. Today shows the plays since midnight, hour by hour, every media server's
  1019. added up, Jellyfin's and Emby's too.
  1020. ```yaml
  1021. sources:
  1022. tautulli:
  1023. - url: http://tautulli:8181 # where Overlook reads Tautulli, directly
  1024. key: ${TAUTULLI_KEY}
  1025. # name: Plex # what the page calls it, if not Plex
  1026. ```
  1027. **Key:** Tautulli's API key, from Settings, Web Interface, with the API on.
  1028. It's the only key Tautulli has, and it can change Tautulli **even through a
  1029. GET**: every command of Tautulli's API is one, such as
  1030. `delete_all_history`, so the GET-only client can't keep this key harmless.
  1031. What does is that the adapter sends only five commands, each of which
  1032. reads, from one list in its code that its test checks (ADR 0011). Tautulli
  1033. takes the key only in the address, so a proxy in front of it may log the
  1034. key: let Overlook reach Tautulli directly, as above.
  1035. Recorded from a scratch Tautulli 2.18 watching a scratch Plex 1.43, with
  1036. invented films and plays (ADR 0008), until someone who runs one records it
  1037. from theirs: the compose file and the scripts that fill and record it are
  1038. in the adapter's [`testdata`](internal/adapters/tautulli/testdata).
  1039. ### Audiobookshelf
  1040. The audiobooks and podcasts, on the Apps page: who listens now, to what
  1041. and on which device; each library, by its books or its podcasts and
  1042. episodes, their hours and the room they take, in red with the items gone
  1043. from the disk or that it can't read; and each podcast's episodes waiting to
  1044. download, with the one downloading. Today shows the minutes listened since
  1045. midnight, and each person's share, with what they listened to.
  1046. ```yaml
  1047. sources:
  1048. audiobookshelf:
  1049. - url: http://audiobookshelf # where Overlook reads Audiobookshelf
  1050. key: ${AUDIOBOOKSHELF_KEY}
  1051. ```
  1052. **Key:** an API key, from Settings, API Keys, made by an admin for a user
  1053. of Overlook's own, of the admin type, with no expiry. Only an admin's key
  1054. reads who listens, and it can change Audiobookshelf **even through a GET**:
  1055. a few of its GETs change things, such as one that restores a backup, so the
  1056. GET-only client can't keep this key harmless. What does is that the adapter
  1057. sends only five paths, each of which reads, from one list in its code that
  1058. its test checks (ADR 0011).
  1059. A session counts on the day it last played, whole, and the hundred newest
  1060. sessions are read, which hold a day's for a household.
  1061. Recorded from a scratch Audiobookshelf 2.37.2 with public-domain books
  1062. read as silence, invented podcasts and invented people (ADR 0008), until
  1063. someone who runs one records it from theirs: the compose file and the
  1064. scripts that fill and record it are in the adapter's
  1065. [`testdata`](internal/adapters/audiobookshelf/testdata).
  1066. ### Seerr
  1067. The requests for films and shows, on the Apps page: how many wait for your
  1068. approval, how many are on their way and how many are there, the problems
  1069. people reported that are still open, in orange, and whether a newer Seerr
  1070. is out or it waits for a restart. Each request waiting for approval is a
  1071. chore, from the day it was made, by its title and who asked, a link to its
  1072. page in Seerr, where you approve or decline it.
  1073. ```yaml
  1074. sources:
  1075. seerr:
  1076. - url: http://seerr:5055 # where Overlook reads Seerr
  1077. key: ${SEERR_KEY}
  1078. link: https://requests.example.com # where the page sends you, if not the same
  1079. ```
  1080. **Key:** Seerr's API key, from Settings, General. It's the only key Seerr
  1081. has, and it can do anything an administrator can, approving requests too,
  1082. but Overlook sends it only with GET requests, which change nothing
  1083. (ADR 0001).
  1084. A request names its film only by its number on TMDB, so Overlook reads each
  1085. title once from Seerr and keeps it, a title never changing; the 20 newest
  1086. requests waiting are listed.
  1087. Recorded from a scratch Seerr 3.5 with invented people asking for
  1088. public-domain films (ADR 0008), until someone who runs one records it from
  1089. theirs: the compose file and the scripts that fill and record it are in the
  1090. adapter's [`testdata`](internal/adapters/seerr/testdata).
  1091. ### Home Assistant
  1092. The home, on the Apps page: Home Assistant's version, or whether it started
  1093. in safe or recovery mode; its automations, those that ran today and those
  1094. whose config it couldn't load, which never run, in red; and each device that
  1095. dropped off, the newest first. The updates it waits to install are chores,
  1096. each a link to its page of updates, as are the batteries below 20%.
  1097. ```yaml
  1098. sources:
  1099. homeassistant:
  1100. - url: http://homeassistant:8123 # where Overlook reads Home Assistant
  1101. token: ${HOMEASSISTANT_TOKEN}
  1102. link: https://home.example.com # where the page sends you, if not the same
  1103. ```
  1104. **Key:** a long-lived access token of a user of Overlook's own that isn't an
  1105. administrator. As an administrator, add the user in Settings, People, Users,
  1106. with **Administrator** off; then log in as it, and make the token in its
  1107. profile's Security tab. A user that isn't an administrator can still use
  1108. every device, such as unlocking a door, with a POST, but Overlook sends only
  1109. GET requests, which change nothing (ADR 0001). It reads `/api/config` and
  1110. `/api/states`, which `default_config` turns on.
  1111. ### Paperless-ngx
  1112. The documents, on the Apps page: how many Paperless-ngx keeps and how many
  1113. wait in its inbox, the room left on its disk, each part it runs on that
  1114. isn't well, such as its search index or its task queue, as it words why,
  1115. and each document it failed to take in, in red with why, until it's
  1116. dismissed in Paperless-ngx. Today shows the documents and the inbox.
  1117. ```yaml
  1118. sources:
  1119. paperless:
  1120. - url: http://paperless:8000 # where Overlook reads Paperless-ngx
  1121. token: ${PAPERLESS_TOKEN}
  1122. ```
  1123. **Key:** the API token of a user of Overlook's own, which sees no document.
  1124. Paperless-ngx shows the parts' health and everyone's failed tasks only to
  1125. staff, so as a superuser, in Settings, Users & Groups, add a user with
  1126. **Admin** on and **Superuser** off, and give it only two permissions: View
  1127. on tasks and View on global statistics (`view_paperlesstask` and
  1128. `view_global_statistics`). Then make its token, as the user, from its
  1129. profile, or with
  1130. `curl -X POST -d username=overlook -d password=… https://paperless.example.com/api/token/`.
  1131. It can see no document and change nothing, and Overlook sends it only with
  1132. GET requests.
  1133. Overlook asks for the API's version 10, so that a newer Paperless-ngx answers
  1134. it the same way.
  1135. Recorded from a scratch Paperless-ngx 3.3.4 filled with invented letters
  1136. (ADR 0008), until someone who runs one records it from theirs: the compose
  1137. file and the scripts that fill and record it are in the adapter's
  1138. [`testdata`](internal/adapters/paperless/testdata).
  1139. ### Nextcloud
  1140. The files, on the Apps page, from Nextcloud's serverinfo app: how many files
  1141. there are, of how many people, and how many used Nextcloud since yesterday;
  1142. the shares, by link and without a password; the room left and the
  1143. database's size; and its version, whether a newer one is out, or, in red,
  1144. whether it's in maintenance. Each app waiting for an update is a chore, a
  1145. link to Nextcloud's page of updates. Today shows the files, and who used it.
  1146. ```yaml
  1147. sources:
  1148. nextcloud:
  1149. - url: http://nextcloud # where Overlook reads Nextcloud
  1150. token: ${NEXTCLOUD_TOKEN}
  1151. link: https://cloud.example.com # where the page sends you, if not the same
  1152. ```
  1153. **Key:** serverinfo's own token, which reads serverinfo's answer and nothing
  1154. else, not even a file. Serverinfo ships with Nextcloud; set its token with
  1155. `occ`, as Nextcloud's own user:
  1156. ```bash
  1157. occ config:app:set serverinfo token --value "$(openssl rand -hex 24)"
  1158. occ config:app:get serverinfo token
  1159. ```
  1160. The counts are Nextcloud's background jobs', so they move as often as its
  1161. cron runs, every five minutes if you set it up so.
  1162. Recorded from a scratch Nextcloud 35.0.2 with invented people and files
  1163. (ADR 0008), until someone who runs one records it from theirs: the compose
  1164. file and the scripts that fill and record it are in the adapter's
  1165. [`testdata`](internal/adapters/nextcloud/testdata).
  1166. ### Gitea
  1167. The updates waiting, as GitHub's are: the open pull requests Renovate
  1168. opened on the repositories you list, chores, never problems. Then, with an
  1169. administrator's token, the Actions runners, on the Apps page, in red when
  1170. one is offline; and each run that failed this week on those repositories,
  1171. in red among the week's events, by its workflow, its repository and the
  1172. commit or pull request that started it.
  1173. ```yaml
  1174. sources:
  1175. gitea:
  1176. - url: http://gitea:3000 # where Overlook reads Gitea
  1177. repos: [example/homelab, example/website]
  1178. token: ${GITEA_TOKEN} # for the runners and private repositories
  1179. # bots: [renovate] # whose pull requests are updates
  1180. ```
  1181. **Key:** an access token of an administrator, since only one can read the
  1182. runners, from Settings, Applications, with only two scopes, both that read:
  1183. **read:repository** and **read:admin**. It never expires. Without a token,
  1184. Overlook reads public repositories only, and no runners.
  1185. Gitea and Forgejo take a few GETs that change something, as Tautulli does:
  1186. Forgejo answers one with a runner's registration token, making one if there
  1187. is none, even for a token that only reads, and anyone with it can register
  1188. a runner of their own, which then runs the jobs and sees their secrets. So
  1189. the GET-only client can't keep this key harmless on its own: what does is
  1190. that the adapter sends only three paths, each of which reads, from one list
  1191. in its code that its test checks (ADR 0011).
  1192. Renovate on Gitea runs as a user you made for it: name that user in `bots`
  1193. unless it's `renovate`. Overlook reads the first 50 open pull requests and
  1194. the first 50 failed runs of each repository, with a request of its own for
  1195. each.
  1196. Recorded from a scratch Gitea 28.3.0 with two act_runner 0.6.1 runners and
  1197. invented repositories and pull requests (ADR 0008), until someone who runs
  1198. one records it from theirs: the compose file and the scripts that fill and
  1199. record it are in the adapter's [`testdata`](internal/adapters/gitea/testdata).
  1200. ### Forgejo
  1201. As [Gitea](#gitea), which Forgejo was forked from and which it still
  1202. answers like: the updates waiting, as GitHub's are; the Actions runners,
  1203. in red when one is offline; and the runs that failed this week.
  1204. ```yaml
  1205. sources:
  1206. forgejo:
  1207. - url: http://forgejo:3000 # where Overlook reads Forgejo
  1208. repos: [example/homelab]
  1209. token: ${FORGEJO_TOKEN} # for the runners and private repositories
  1210. # bots: [renovate] # whose pull requests are updates
  1211. ```
  1212. **Key:** as Gitea's: an administrator's access token, from Settings,
  1213. Applications, with only **read:repository** and **read:admin**. Forgejo
  1214. answers a GET for a runner's registration token, which is why the adapter
  1215. sends only the paths on its list (ADR 0011).
  1216. Recorded from a scratch Forgejo 17.0.1 with two Forgejo Runner 13.2.1
  1217. runners, filled as Gitea's is (ADR 0008), until someone who runs one
  1218. records it from theirs: the compose file and the scripts that fill and
  1219. record it are in the adapter's
  1220. [`testdata`](internal/adapters/forgejo/testdata).
  1221. ### Can't be read
  1222. These tools can't be read the way Overlook reads, with GET (ADR 0001), one
  1223. login (ADR 0009) and, for a source that changes things on GET, a fixed list
  1224. of reads (ADR 0011), or are left out on purpose. Each names the decision it
  1225. runs into, and none gets an adapter until that changes:
  1226. - **Backrest and restic**: restic has no API, every call to Backrest's is a
  1227. POST, and its metrics say how the last backup went, not when (ADR 0001).
  1228. - **Caddy**, on purpose: its admin API has no login, and its only lock is a
  1229. TLS client certificate, so opening it to Overlook opens it to anyone there
  1230. to rewrite Caddy's config (ADR 0001).
  1231. - **Deluge, Transmission, Komodo and Zabbix**: every read is a POST
  1232. (ADR 0001).
  1233. - **Dockge**: it speaks only socket.io (ADR 0001).
  1234. - **Plex on its own**, on purpose: its token is your whole Plex account,
  1235. other servers and friends too, so Overlook reads Plex through
  1236. [Tautulli](#plex-through-tautulli) (ADR 0011).
  1237. - **Synology DSM**: its only documented login is a GET with the password in
  1238. the address, where logs keep it, and how to read its health isn't
  1239. documented (ADR 0009).
  1240. - **TrueNAS**: TrueNAS 27 removes the REST API, which leaves only a
  1241. WebSocket (ADR 0001).
  1242. - **Unbound**: its statistics come only from `unbound-control`, over TLS
  1243. with a client certificate, or on the same machine (ADR 0001).
  1244. - **Vaultwarden**, on purpose: reading more than its version takes the
  1245. admin token, which can delete every user (ADR 0009).
  1246. Others are left out for a reason of their own:
  1247. - **Dozzle and Authelia**: they show nothing more than whether they answer,
  1248. which a check already says.
  1249. - **Readarr**: retired in June 2025.
  1250. - **The UniFi Network application on its own**, without UniFi OS: it has
  1251. no API keys, and Ubiquiti dropped it in Network 11, for UniFi OS Server,
  1252. which [UniFi](#unifi-network) reads.
  1253. - **Watchtower**: no longer kept, and archived in December 2025.
  1254. ## No login
  1255. Overlook has no accounts and no login: anyone who can open the page sees
  1256. all of it. It never shows a key, but it does show your hosts, names and
  1257. what is wrong. Keep it on your LAN or behind your VPN, or put it behind
  1258. your reverse proxy's own authentication, such as forward auth to your
  1259. identity provider.
  1260. Behind a login, let `/apple-touch-icon.png` through it, and only that: an
  1261. iPhone adds the page to its home screen without your login, so it asks
  1262. for the icon there, and shows a letter if it gets the login page instead.
  1263. It is Overlook's logo and nothing more.
  1264. ## Agents, through MCP
  1265. An AI agent can read what the page shows, if you turn it on. Overlook then
  1266. answers the Model Context Protocol at `/mcp`, at the page's own address,
  1267. with no login, as the page has none, so whoever can open the page can read
  1268. it there too:
  1269. ```yaml
  1270. # overlook/overlook.yaml
  1271. mcp: true
  1272. ```
  1273. Restart Overlook, and give your agent that address as an MCP server over
  1274. HTTP, such as `http://overlook.example.com:8080/mcp`. With Claude Code,
  1275. that is
  1276. `claude mcp add --transport http overlook http://overlook.example.com:8080/mcp`.
  1277. - **It can only read.** It has six tools, one for each part of the page,
  1278. and none of them changes anything, in Overlook or in your homelab:
  1279. `problems` (what's wrong, the homelab's state and each area's, and
  1280. whether each source answered), `area` (one area and its state, as its
  1281. own page shows it), `today` (the figures), `this_week` (the problems and
  1282. events of the last seven days), `chores` (the chores and the updates)
  1283. and `apps_and_tools` (each link, its state and the check that says
  1284. whether it answers). Every state is the one the page shows.
  1285. - **It reads the snapshot and nothing else**: the one the page is drawn
  1286. from, at most 30 seconds old, never a key or a source's own answer. Each
  1287. tool returns its part as JSON, each message key with its English words
  1288. beside it and its values next to them, never a sentence Overlook put
  1289. together itself.
  1290. - **The model behind the agent sees your homelab**: its hosts, names and
  1291. problems, wherever that model runs. That is why MCP is off until you
  1292. turn it on.
  1293. - **A website can't reach it.** It refuses a request from a page in your
  1294. browser that isn't Overlook's own, so that a site you visit can't read
  1295. your homelab through you.
  1296. - It speaks MCP's current revision, 2026-07-28, and the three before it,
  1297. 2025-11-25, 2025-06-18 and 2025-03-26, which many agents still speak. It
  1298. answers each request on its own and whole, with nothing streamed
  1299. (ADR 0015).
  1300. ## Your own look
  1301. A `custom.css` beside the config is loaded after the page's own
  1302. stylesheet, so it can change any colour, size or font:
  1303. ```css
  1304. /* overlook/custom.css */
  1305. :root {
  1306. --m-accent-2: #3cad4b; /* the accent, green */
  1307. --m-content-max: 1400px; /* a wider page */
  1308. }
  1309. ```
  1310. The page's colours, sizes and fonts are the `--m-` properties at the top
  1311. of [`web/style.css`](web/style.css): the dark page's, then the light
  1312. page's, under `:root:where([data-theme="light"])`, which the page sets
  1313. where your system is light or Light is chosen in its footer. A property
  1314. your custom.css sets changes both; set under the same selector, it changes
  1315. the light page only. The page stays one page: custom.css changes how it looks,
  1316. not what it shows.
  1317. ## Translating
  1318. The page speaks the language of your browser, and English for any word a
  1319. translation lacks. Besides English, it speaks Simplified Chinese, German,
  1320. French, Spanish, Brazilian Portuguese, Russian, Polish, Japanese, Korean and
  1321. Italian. Claude Code translated each in two passes, the second a review as
  1322. someone who speaks it would read it, and looked at the page in each for
  1323. words that don't fit. None has yet been read by someone who speaks it, so
  1324. a correction is welcome, and so is a speaker who would keep one. A
  1325. translation is one file; [CONTRIBUTING.md](CONTRIBUTING.md#translating)
  1326. says how.
  1327. ## What's next
  1328. `v0.8.0` is the newest release, and [the releases](https://github.com/bnlqn/overlook/releases)
  1329. say what each one brought. v0.7.0 finished the road to v0.7, below, which
  1330. took Overlook where more homelabs are, as
  1331. [selfh.st's 2025 survey](https://selfh.st/survey/2025-results/) counts
  1332. them, and kept it sound as they came. v0.8.0 came between roads, with
  1333. Tdarr and a fix to the setup page's download of the keys. The road to v0.9
  1334. is still being decided.
  1335. 1. [x] A Home Assistant add-on, kept here beside Unraid's template, so
  1336. that Overlook installs inside Home Assistant OS, which three
  1337. homelabs in ten run, and opens in its sidebar.
  1338. 2. [x] The next tools by how many homelabs run them, each recorded from a
  1339. scratch instance (ADR 0008), one pull request each, each run by
  1340. about one homelab in five:
  1341. [Nginx Proxy Manager](https://github.com/bnlqn/overlook/issues/77),
  1342. [Audiobookshelf](https://github.com/bnlqn/overlook/issues/78) and
  1343. [Traefik](https://github.com/bnlqn/overlook/issues/79).
  1344. 3. [x] Two translations or more, each kept by someone who speaks it
  1345. (ADR 0006), and the page looked at in each, at desktop and phone
  1346. width, for words longer than English's.
  1347. 4. [x] A check's results readable without colour or a mouse: its last 30
  1348. said in words, such as 28 of 30 passed and the last one failed at
  1349. 14:02, for a screen reader and the keyboard, and a failed result
  1350. told from a passed one by more than red and green. Then the page is
  1351. gone through with a screen reader and in forced colours, and what
  1352. doesn't read is fixed.
  1353. 5. [x] The setup page asks for a code from the log before its first try,
  1354. so that no website can have it read an address in the homelab, not
  1355. even one that points its own name at Overlook's address (amends
  1356. ADR 0014). SECURITY.md then loses the gap it accepts.
  1357. 6. [x] Each scratch instance recorded again every week, at its source's
  1358. newest version: a workflow starts it from its compose file, fills
  1359. and records it with its own scripts, reads what it recorded with the
  1360. adapter, checks that with `adaptertest.Validate`, and opens an issue
  1361. when either fails. A source that changes its answers is then found
  1362. before an owner finds it.
  1363. 7. [x] Each state decided once and carried in the snapshot: each check's,
  1364. app's, tool's, area's and the homelab's. The page words them and
  1365. MCP gives them, so an agent learns the state the page leads with,
  1366. and a change to how a state is decided is made in one place, never
  1367. in the page and MCP both (ADR 0017).
  1368. The [adapters wanted](https://github.com/bnlqn/overlook/issues?q=is%3Aissue%20is%3Aopen%20label%3Aenhancement)
  1369. are open as issues: if you run one of them, its issue says what an
  1370. adapter for it takes.
  1371. ## Contributing
  1372. [CONTRIBUTING.md](CONTRIBUTING.md) says how to set up, what every change
  1373. passes, how to add an adapter and how Overlook is written. The words the
  1374. project uses are in [CONTEXT.md](CONTEXT.md) and its decisions in
  1375. [docs/adr](docs/adr). Ask a question in
  1376. [Discussions](https://github.com/bnlqn/overlook/discussions), and report a
  1377. vulnerability privately, as [SECURITY.md](SECURITY.md) explains. Everyone
  1378. who takes part keeps to the [code of conduct](CODE_OF_CONDUCT.md).
  1379. ## Licence
  1380. Overlook is under the [MIT licence](LICENSE). The page ships the Inter
  1381. font, under the SIL Open Font License ([`web/fonts`](web/fonts)), and logos
  1382. of common apps, under the Apache License 2.0 but for UniFi's, which is
  1383. Ubiquiti's own, and Checkmate's, adapted from Cburnett's chess set under
  1384. CC BY-SA 3.0 ([`web/icons`](web/icons)), each logo its owner's trademark.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.