Overlook

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

What's wrong, how each area of the homelab is, and what it did today and this week, on a page that is the same for every homelab. Overlook reads the tools you already run and changes nothing. If you turn on MCP, your AI agent can ask it what the page shows, and can't change anything either. See the demo, drawn from a homelab that doesn't exist.

It reads:

• Check engines: Gatus, Uptime Kuma, Grafana, Prometheus and Alertmanager, Checkmate
• Servers: Proxmox VE, Beszel, Docker, Portainer, NUT
• Network: UniFi Network, AdGuard Home, Pi-hole
• Storage: Proxmox Backup Server, Syncthing, and the pools, storage and backup runs of Proxmox VE
• Apps: Immich, Jellyfin, Emby, Plex, through Tautulli, Radarr, Sonarr, Prowlarr, qBittorrent, Seerr, Home Assistant, Paperless-ngx, Nextcloud, Gitea, Forgejo
• Chores: GitHub, iCalendar to-do lists

What it can't read, and why, is under Can't be read.

What it shows

• What's wrong: the problems, which are the checks your check engine alerts on, for as long as they fail. Overlook runs no check and sends no alert, so the page and your alerts always agree.
• How each area is: Servers, Network, Storage and Apps, each up, degraded (a problem, but it still works, such as DNS with one of two resolvers down) or down, with its checks' last 30 results and a page of its own with what its sources add, such as a host's guests or a resolver's top clients.
• Today: a figure from each source, such as guests up, DNS lookups, photos or what the UPS draws.
• This week: each area's problems and events along the last seven days, and the list of what happened, as far as your sources remember it.
• Your apps and tools, each a link with a dot that says whether it answers.
• The chores: the ones on your to-do list that are due or come this week, the updates waiting for your merge or to be installed, the batteries to change, the devices waiting to be adopted and the requests waiting for your approval. You do a chore where it waits, such as marking it done on the list, never on the page, and a chore is never a problem.

The page is light where your system is light, and dark otherwise. On a phone, your browser's Add to Home Screen, or Install app, puts it there as an app of its own.

What it never does

• It never changes anything. Overlook sends a source only GET requests, and a login where a source offers no other way in, which changes nothing but a session; it sends NUT only LIST VAR, which reads. The client it reads with refuses every other request. Some keys it holds could do anything (AdGuard Home has no read-only users, and Radarr's and Sonarr's keys are admin keys), and this is what keeps them harmless. Tautulli changes things on GET too, and Gitea and Forgejo for a few paths, so their adapters send only the commands and paths that read, from a list their tests check (ADR 0011).
• It never runs a check or sends an alert. Your check engine does both.
• It remembers nothing. No database and no volume: it reads every source when the page asks, at most every 30 seconds, so an Overlook nobody looks at sends nothing into your homelab. What happened this week is what your sources remember.
• It never sends a key to the browser. The server reads every source and gives the page a snapshot of what it read, never a key or a source's own answer, and gives an agent no more, if you turn MCP on.
• It never asks where to put things. The page is fixed: your config says which sources fill it, never where anything goes. There are no widgets to arrange.
• It never calls anywhere you didn't name. No telemetry and no update check; the page's fonts, icons and manifest come from Overlook itself.

Quick start

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.5
    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: 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/, 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. .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, anyone who can open it can have Overlook read an address they type, as SECURITY.md says, so save the files soon.
• 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.5 for the newest 0.5 release, or a version such as 0.5.0. It holds the binary and the CA certificates it checks HTTPS sources with, and nothing else.

Without Docker, each release 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

It reads .env beside the config there too, and shows the setup page until the config exists.

On Unraid, install Overlook from the Apps tab, where its listing is: search for Overlook, and apply its template. Its config folder is /mnt/user/appdata/overlook, it runs locked down as above, and Unraid gives it TZ itself. Its WebUI opens the setup page, which says how to save the two files on Unraid. To link the Unraid server itself in the sidebar, as a tool, give it icon: unraid.svg, which Overlook ships.

Configuring

overlook.example.yaml shows every source with comments. Overlook reads the config once, at start, and refuses a key it doesn't know, so a typo stops it rather than going unnoticed.

Sources. Under sources:, each adapter has a list, so two AdGuard Home resolvers are two entries under adguard:. Each source has a name, which the page uses. Each adapter gives one, such as Gatus, and two sources can't share one, so two of one adapter need names of their own. With two of one adapter, the page names each one's sections, figures and events, and adds up what adds up, such as two Proxmox hosts' guests, split by source. What each adapter reads, its config and the least key it needs are under Adapters below.

Areas. The page has four, always the same: Servers, Network