Your homelab

A homelab is the computers you run yourself: servers, a NAS, a machine with a graphics card for AI. If you have one, bromigOS can put it on your desktop and use it:

• the LAB panel shows its health at a glance;
• the lab deck and other holograms show it in 3D;
• VECTOR can tell you what it’s doing, and use its AI models;
• AI work, such as pictures and VECTOR’s voice, can run on its graphics cards instead of a paid service (Creating with AI);
• the worlds show its health: Tidewell’s lighthouse, for example.

bromigOS works with the services you already run. It doesn’t need a particular set-up. You don’t need a homelab to use bromigOS. Without one, these parts stay hidden.

To create VMs, form a Kubernetes cluster or install services, use Lab provisioning. It includes monitoring and waits for your approval before allocating resources.

Connect your homelab

1. Run:

   bromigos setup homelab
   

2. It offers Find my lab first (below). Type y to let it look for your machines. Or type n, and give it the names or addresses of your homelab’s machines. Either way, it checks each machine for the services it knows, and only counts a service whose own interface answers.

3. Check what it found:

   bromigos homelab status
   

4. Run bromigos restart live widgets vector, so the background, the panels and VECTOR pick it up.

Running bromigos setup homelab again only adds what’s new. It never rewrites your own changes.

Some useful options:

bromigos setup homelab --find                       # look for your machines first
bromigos setup homelab --hosts nas,gpu-box          # check these machines
bromigos setup homelab --url https://prometheus.lan  # add one service by its address
bromigos setup homelab --print                       # show what it would add; change nothing

Find my lab

You don’t need to know every machine’s name. Find my lab looks in what this computer already knows about your network:

bromigos setup homelab --find

It first lists what it will read, and asks. Nothing is read until you type y:

• devices that announce themselves on your network, such as a NAS, Home Assistant, a printer or a camera;
• this computer’s list of nearby devices, and the names your DNS gives them;
• your Tailscale devices, if you use Tailscale;
• what your connected services already know, such as your router’s clients (UniFi), Prometheus’s targets, Kubernetes nodes and Proxmox VMs. On a first run you haven’t connected any, so this part is skipped.

Then it asks separately whether to read the Host lines of ~/.ssh/config. It never reads your keys.

It never scans address ranges, never signs in to anything, and sends nothing off your network. It checks only the machines it found, at private addresses, for the services bromigOS knows.

You see each machine once, grouped by kind: lab machines, smart home, cameras, robots, printers, media and other. Each line says where it was seen. Under it are the services bromigOS can add, numbered, and what it found but doesn’t support yet. Type the numbers you want, or press Enter for all of them.

For mDNS, the announcements most devices make, install python-zeroconf first:

sudo pacman -S python-zeroconf

Machines set up with bromigos lab provision announce themselves, so Find my lab always finds them. Settings › Lab has a Find my lab… button too.

If you run Kubernetes, bromigOS never picks a cluster on its own. Name yours when it asks, or with --kube-context.

What it understands

Many of these need no address of their own. bromigOS finds them through your metrics or your cluster, once it knows those.

The ALERTS panel and Lab alert card leave out Watchdog and InfoInhibitor. These are monitoring helpers, not problems to fix. Other info-level notices stay visible alongside warnings and critical alerts.

If a service is missing, the parts of the desktop that need it are hidden. If a service stops answering, it shows as “unreachable”. To check everything, and get plain-words advice on what to fix, run:

bromigos lab doctor

YouTube downloads with Pinchflat

Pinchflat downloads YouTube channels and playlists into your media library. Add it to homelab.toml. If its web page asks for a user and password, put them in a file as user:password and name the file in auth_ref:

[[source]]
type = "pinchflat"
endpoint = "http://pinchflat.lan:8945"
auth_ref = "@file:~/.local/share/bromigos/pinchflat-login"

Without a password, it needs Pinchflat’s route token instead. The token is in the OPML link on Pinchflat’s Sources page: copy the part after route_token= into a file, and name it in route_token_ref.

To see its download queue too, start Pinchflat with ENABLE_PROMETHEUS=true.

For YouTube cookies (bromigos lab youtube cookies), say where Pinchflat reads them, with cookies_store in the same source:

• cookies_store = "file:/srv/pinchflat/config/extras/cookies.txt" when its config folder is on this machine or a share you have mounted;
• cookies_store = "vault:secret/lab/pinchflat#cookies" when your lab copies Pinchflat’s cookies from Vault.

bromigos lab youtube sync makes each downloaded playlist a playlist in Jellyfin or Plex, in YouTube’s order. It needs an API key for each media server: put it in a file and name the file in that server’s source as token_ref. See The lab console.

Media requests

Start with Your media to find, download and watch a title.

To ask your lab for films, shows and music (bromigos lab media, see The lab console), add a source for each app you have. Each needs its address and its API key, which is on the app’s Settings › General page. Put each key in its own file, as above.

[[source]]
name = "seerr"
type = "seerr"
endpoint = "http://seerr.lan:5055"
auth_ref = "@file:~/.local/share/bromigos/seerr-key"

[[source]]
name = "sonarr"                  # the same for radarr, lidarr, prowlarr and bazarr
type = "arr"
endpoint = "http://sonarr.lan:8989"
auth_ref = "@file:~/.local/share/bromigos/sonarr-key"

[[source]]
name = "qbittorrent"             # and sabnzbd, slskd: for each download's progress
type = "qbittorrent"
endpoint = "http://qbittorrent.lan:8080"
auth_ref = "@file:~/.local/share/bromigos/qbittorrent-key"

[media]
audio = ["en", "ja"]             # your audio languages, best first
subtitles = ["en"]

Seerr is optional. Without it, requests go straight to Sonarr, Radarr and Lidarr. With it, they show in Seerr’s Requests too. qBittorrent needs a WebUI API key (version 5.2 or later), or user_ref and its password. slskd takes its password, and import_path: the folder its downloads land in, as Lidarr sees it.

Keep passwords out of the file

Your homelab’s settings are in ~/.config/bromigos/homelab.toml. Where a service needs a password or a token, the file holds a reference to it, never the secret itself. So you can keep the file in a public dotfiles repository.

Your own panels without code

You can add a gauge, a chart, a number, a status light or a table to the desktop by describing it in homelab.toml, or in a file in ~/.config/bromigos/homelab/panels/. It takes the theme’s colours like every other panel. For example, a light that shows whether a service answers:

[[panel]]
name = "jellyfin"
kind = "status"
url = "http://jellyfin.lan:8096/health"

Each panel reads one thing: a metrics query, an address to check, or one of the kinds of service above. The developer docs’ homelab.md lists every option, with more examples.

The lab console

bromigos lab shows your whole homelab at once, runs AI jobs on its graphics cards, and checks it for problems. See The lab console.

More

The developer docs’ homelab.md has every kind of service, the settings file in full, and how to write support for a new service.

The console also works on plain Arch. Follow Install on plain Arch for the standalone bromigos-lab AUR package.