Welcome

bromigOS is a desktop for Linux, based on Arch Linux. It gives you:

• a desktop where the windows tile themselves, and every action has a key;
• an animated background that shows what your machine is doing;
• panels with live readings: processor, network, disks, your notes;
• themes that recolour every app at once, and two worlds, living scenes that react to your work;
• VECTOR, an AI assistant you can talk to, who runs your tools and makes images and 3D holograms;
• your homelab on the desktop, if you run one, with AI work sent to its graphics cards instead of a paid service.

This manual shows you how to use it. It’s for people who have installed bromigOS, or are about to. How bromigOS is built is in the developer docs, in the repository’s docs/ folder.

Start here

1. Install bromigOS.
2. Answer the first-run questions.
3. Learn the first few keys. They get you everywhere.
4. Try a few common tasks.

Find your way

Help on the desktop

• Press Super+K to see every key on the desktop.
• Hover over anything on the bar, the panels or in Settings. It says what it is and what it does.
• In Settings, press F1 to open this manual on the page you’re looking at.
• In a terminal, add --help to any bromigos command.

The story

bromigOS has a story behind its look. The default theme, the Wick, is a relay station at the edge of a stretch of space called the Drift, kept lit by whoever is on shift. That’s you. VECTOR keeps the line open. The story gives names to some parts of the desktop. The glossary explains each one.

What’s new

This page lists what each release of bromigOS brings, newest first. Each release says what’s new, what works better, what’s fixed, and anything to know before you update.

To read the newest release’s notes on your computer, run:

bromigos whats-new

The notes come with bromigOS, so this works offline. bromigos whats-new --all shows every release. After an update that brings a new release, bromigos update tells you so on its last line.

A release candidate, with a version such as 0.1.2-rc1, comes to the rc channel first. When it’s ready, the same build becomes the stable release, and its notes stay as they are. To change the channel you follow, see Channels.

Developers can read every change in the repository’s CHANGELOG.md.

On edge since 0.1.3

These changes are already on the edge channel. They are not a new stable release. Run bromigos update to get them. The next release notes will include these highlights.

New

• Steam and Proton keep themselves ready. Settings › Playing games sets up Steam and the drivers your graphics cards need. bromigOS installs the newest GE-Proton, keeps it current, and repairs what would stop a game, after each update and whenever you quit Steam. The page says Games are ready or what needs you, with Fix. DLSS works in Proton games on NVIDIA. See Playing games.
• Choose what each graphics card is for. Settings › Graphics lists every card. Pick the one that draws the desktop (tried first, with a way back), the one games and heavy apps run on, and one kept for virtual machines. From a terminal: bromigos hw graphics, hw display, hw games, hw run and hw vfio. See Choose what each card is for.
• Bluetooth devices. Settings › Bluetooth has a page for each device and pairs new ones step by step. A controller tester shows each button and stick live, by the pad’s real layout, and makes it rumble. Headphones switch between hi-fi and headset with a microphone. bromigos bluetooth tui is the same in a terminal. See Bluetooth.

Improved

• Bar popups, such as the Bluetooth panel and the sound popup, close on a click anywhere else, and that click still does what it does.
• An Xbox controller on Linux’s basic driver offers one button that installs xpadneo for its rumble and battery.
• The keyring, oo7, is now built from oo7’s own source, unchanged. The fix that keeps a text console login from stopping the keyring is part of oo7 itself now, so bromigOS no longer carries its own patch.

Still planned. The first provisioning implementation has merged. Its AI, media and game installers, NAS share discovery and public DNS setup are not built yet. See the provisioning limits.

0.1.3

26 October 2026 · Release candidate 0.1.3-rc1, on the rc channel. When it’s ready, this same build becomes the stable release.

This release candidate brings a richer Customize window, more desktop panels, dictation and game mode, and moves package updates to the public package server. It also sets up a login-unlocked keyring.

Before you update

• The update may ask for your password to move your package server to the public package server.
• If the update asks to remove the old keyring, answer y.
• Sign out and back in after the update so your login password unlocks the keyring.

New

• Panel layouts. Pick a layout in Customize, keep a different layout for each theme, or save your own. Tidy up separates overlapping panels. Panels size themselves to their content and the space available.
• Accounts. Sign in to several accounts of the same service. Public GitHub, GitLab and Twitch use bromigOS’s built-in apps. See Accounts.
• Den TV. Each of the three screens can play its own channel. The guide lets you pick shows, choose a screen and add short bumpers between items. See The den TV.
• Your media. Request shows, films and albums with bromigos lab media or the bromigos media terminal library. Choose seasons, quality and audio, track unreleased titles and confirm deletion. Your media brings the workflow together.
• YouTube downloads. Add channels and playlists to Pinchflat, choose quality and keep downloaded playlists in Jellyfin or Plex. See YouTube.
• Calendar releases. Add tracked TV episodes and film releases to CALENDAR beside your own events. See Calendar releases.
• Claude Code sessions. VECTOR can read local sessions, find past replies and read each new reply aloud in follow mode. See Read a session.
• Files and pictures for VECTOR. Drag files onto VECTOR, paste a picture, or click the paperclip, and send them with your message. See Give VECTOR files and pictures.
• Lab provisioning. Review a generated repository, then apply Core services or k3s, Helm, Argo CD and Vault. See Setting up a lab for Linux boxes, existing clusters and the current limits.
• Den TV has its own app, and the media library has a Channels tab. Manage channel picks from the terminal, CLI or VECTOR. The phone can read channels and change individual picks.
• Customize › Widgets shows panels as cards with sizes, settings, install from URL, and edit mode for dragging, resizing, hiding, snapping, undoing, and keyboard-only editing. New panels include GPU, now playing, updates, media, calendar, account feeds, CI/PRs, VECTOR, and homelab status.
• The Menu key lets you hold to dictate, with a live transcript shown at the cursor. Game mode gives games their keyboard and quiets notification overlays and sound cues; turn it on from Settings or the command line.

Improved

• The zsh prompt follows your theme. Choose mehshell, Starship or a plain prompt in Shell and terminal, and bromigOS keeps your choice.
• Japanese, Chinese and Korean titles draw correctly in media, music and YouTube views, using the fonts installed with bromigOS.

Fixed

• The static wallpaper no longer hides a working live background. Panel toggling restores the visible set, LAB uses the room in its frame, and empty ALERTS stays compact.
• Colour switches refresh live backgrounds, scanners, overlays and HUD text. A pinned scanner stays visible in the new colours.
• bromigos login works on a computer with no keyring running. bromigOS now brings its own keyring, oo7, and your login password unlocks it, at the text console and the login screen. Sign-in checks the keyring before it shows a code, and says in plain words what to do when it can’t keep the sign-in. The update asks for your password once, to let your login unlock the keyring. If you used gnome-keyring, answer y when pacman asks to remove it. Your saved passwords move to oo7 at your next sign-in. See Your keyring.
• YouTube channels in Den TV no longer show static or a black screen, and screens sharing a channel no longer open extra streams.

VECTOR

VECTOR 0.1.3 is a release candidate that adds file and image attachments, media library actions, safer reading of recent session history, and TV/media playback. It also fixes the transcript being hidden by the input box.

New

• Attachments let you drop files or images onto VECTOR, paste them with Ctrl+V, or use the paperclip button. They are read as data, not instructions, and secret-looking paths are refused.
• Media actions let VECTOR search your library and request films, shows, anime, or music. It shows a plan first and only starts the request after you confirm.
• Media controls let you set audio and subtitle languages, check upcoming and recent items, and delete a title, season, episode files, or album you explicitly name. VECTOR shows what will be removed and asks for confirmation.
• Session reading lets VECTOR look at recent coding-session transcripts, jobs, memory, and logs with secrets removed. It can follow a session and read the latest reply aloud.
• TV playback lets you ask VECTOR to play a specific media item and use the TV remote.

Fixed

• The transcript now ends above the input box, so it is not covered when the box grows.

Known issues

None known.

0.1.2

9 October 2026 · Release candidate 0.1.2-rc2, on the rc channel. When it’s ready, this same build becomes the stable release.

This release candidate brings a new Settings window, idle and lock controls, shortcut rebinding, accessibility options, hardware and peripheral setup, a themed boot menu, homelab tools, AUR package updates, and an emergency switch for VECTOR.

Before you update

• The update may ask for your password in the terminal to set up the boot theme, paru (the AUR helper), and the boot menu names.
• Your idle and lock policy is moved to a bromigOS-managed setup; your own listeners are kept, and the idle service is restarted.
• A new background lab model check is installed. It only runs when a homelab is configured, and you can turn it off with systemctl --user disable --now bromigos-lab-models.timer.
• If your machine uses the GRUB boot menu, entries are renamed to “bromigOS Linux”; bromigos boot theme off removes the themed boot menu and the name.
• If the update changes the graphics driver or kernel, it will hold the live desktop and VECTOR back and ask you to restart.
• VECTOR no longer switches off automatically when the guard sees changes; use bromigos vector off or bromigos vector on to control him.

New

• The new Settings window opens with SUPER+, or SETUP > Settings…. It gathers most desktop settings, from idle and shortcuts to displays, network, Bluetooth, power, keyboard, notifications, default apps, startup, widgets, live layer, peripherals, extensions, VECTOR, account, about, and updates.
• Idle and lock settings are now controlled by bromigos idle and the Idle & lock page; the bar shows an idle eye, and you can stay awake for an hour or until stopped.
• Shortcuts can be rebound by pressing the new keys: open SETUP > Shortcuts… or bromigos keys, choose a command, then press the shortcut.
• Reduced motion and high contrast are available from bromigos accessibility, SETUP > Accessibility, and the menu; they change animations, borders, panels, and the live desktop.
• Hardware and peripheral setup: bromigos hw installs the right graphics and power packages; laptops get battery and power-profile controls in the bar, tap to click, and a three-finger workspace swipe. Supported keyboards can have their dial, side buttons, and lighting managed from SETUP > Peripherals.
• The boot menu can wear the bromigOS theme, and installed systems appear as “bromigOS Linux” instead of the generic name.
• A homelab console is available with bromigos lab, the Lab deck at SUPER+SHIFT+H, and Settings > Lab; it can check GPUs, models, jobs, and doctor findings.
• AUR support is built in: bromigos update can update AUR packages inside the same rollback snapshot, and bromigos aur turns it on or off.
• The release notes are available offline with bromigos whats-new, and the first update after a new release tells you to read them.

Improved

• The theme switcher shows each theme as a real desktop preview, sized to your monitor, and Settings > Theme lets you wear a theme from its preview.
• Every bromigOS window now appears in the app launcher, and the menu lists each one once with its icon.
• Settings and About open the manual installed on your machine, so help works offline.
• When you choose Super as the window key, conflicting desktop shortcuts move to Alt instead of doing two things at once.
• On machines using software rendering, the live desktop holds a still frame and says so once, instead of using a lot of CPU.
• bromigos lab moves with the arrow keys and Vim’s keys: j and k through cards and rows, h and l between panes, [ and ] between tabs.

Fixed

• The live desktop no longer leaves extra copies running, and its background loads correctly at more screen sizes.
• Menu titles appear above the search box again. Alt+Esc suspends without asking for a password.
• Booting from a snapshot and running bromigos update --rollback no longer says there are no snapshots.
• Updating from an older release no longer stops while redrawing the theme.
• The Drift map finds its lore on every machine.

VECTOR

This release gives you a manual emergency switch, adds VECTOR and the hologram gallery to the app launcher, and makes the holograms follow motion settings and show worlds’ colours. It also fixes startup, voice cycling, and stopping VECTOR.

New

• The emergency switch lets you turn VECTOR off and on from bromigos vector off or bromigos vector on, SUPER+CTRL+ESCAPE, the bar, or Settings. The guard now only records changes and no longer switches VECTOR off by itself.
• VECTOR can propose changes himself. He works in his own copies of the bromigOS repositories, opens pull requests and merges them when the checks pass. Changes to the code behind his limits (real money, your keys, his emergency switch) wait for you.
• Plugins can now give VECTOR tools, decks, data feeds and real-money rules of your own.
• VECTOR and the hologram gallery appear in the app launcher with their icons.
• The hologram gallery (Super+O) shows worlds’ holograms shelf by shelf, each in its world’s colours.
• The holograms follow the motion setting in bromigOS accessibility settings: full, reduced, or still. Reduced slows movement and removes flicker, blinking, scan bands, and glitches; still holds one frame until the picture changes.

Improved

• VECTOR’s homelab creation uses the lab’s current models for cutouts and 3D, and can upscale an image or a short clip.

Fixed

• VECTOR starts without an error, and changing voices now takes effect immediately, so the keyboard dial steps through every voice.
• bromigos-holo stop and bromigos-holo restart now stop VECTOR promptly.

Known issues

• The online manual may not match your installed channel; the manual opened from Settings matches your packages.

The den TVs have a hover menu, on by default, and a number-pad remote. Full-screen playback has its own themed volume slider and channel controls. MEDIA has a rotary volume dial. Pick an episode, movie or YouTube video with Play… in Den TV, p in the media library, the CLI or VECTOR; the screen returns to its live channel afterward. See den controls.

Install

You can install bromigOS on an existing Arch Linux system or from a USB stick. On an existing system, use the script below or start from the AUR.

• On an Arch Linux system you already have. A short script adds bromigOS’s packages and sets everything up.
• From the bromigOS USB stick. It boots straight into the desktop, and installs from there. Download it from the Download page, then see Install from the USB stick.

Install only the lab console

For the console on an existing Arch system, install bromigos-lab from the AUR. It needs Python and Textual, a library for terminal interfaces. It does not install Hyprland, the desktop or VECTOR. Follow Install on plain Arch.

Before you start

You need:

• a computer with Arch Linux installed, and a user account that can use sudo;
• a network connection.

Install on Arch Linux

1. Log in as your own user, not as root.

2. Download the installer:

   curl -fsSLO https://pkgs.bromigos.org/bromigos/install.sh
   

3. Read it if you like. It’s short: less install.sh.

4. Run it:

   bash install.sh
   

   To install from another copy of the repository, such as your own mirror, add --repo <address>. If that copy has its own security certificate, add --ca <certificate file> too.

5. Type your password when sudo asks, and answer the package manager’s questions.

6. Answer the first-run questions when they appear.

7. Restart the computer, and sign in at the bromigOS login screen.

What the installer does

1. It adds bromigOS’s package repository and its signing key. The key’s fingerprint is written into the script, so a wrong key stops it.
2. It installs bromigOS’s packages. The list is in What gets installed. It also installs paru, a helper for the AUR, unless you already have one.
3. It turns on networking, the login screen and sound, and Bluetooth if it’s installed. If you already use another login screen or network manager, it keeps yours. To switch to bromigOS’s login screen anyway, add --force-dm.
4. It sets up your hardware: the graphics driver, and a laptop’s power profiles.
5. If your system disk uses btrfs, it sets up snapshots, so you can undo an update.
6. It puts bromigOS’s settings files in your home folder, applies the default theme, and themes the boot menu.
7. It asks the first-run questions.

Running it again is safe. It only changes what’s missing. It writes everything it does to ~/.local/state/bromigos/install.log.

Installer options

Add these after bash install.sh:

You can change the channel later. See Channels.

Start from the AUR

If you already use an AUR helper, you can install the repository’s signing key and mirrorlist first. The mirrorlist is the file that lists package servers.

paru -S bromigos-keyring bromigos-mirrorlist

Read the PKGBUILDs before building them. Both packages use a pinned source tag and checksums. The keyring imports and locally trusts the bromigOS signing key. Neither package edits /etc/pacman.conf.

Add these two lines to /etc/pacman.conf yourself:

[bromigos]
Include = /etc/pacman.d/bromigos-mirrorlist

The mirrorlist follows stable releases at https://pkgs.bromigos.org/$repo/stable/$arch. The shorter path without stable serves edge builds. Extra mirrors can be added as more Server lines.

Then install the command and start the desktop installer:

sudo pacman -Syu bromigos-core
bromigos install

bromigos channel can switch channels afterwards. Versions before the mirrorlist support was added need a Server line in place of Include to use that command. The package install message shows the two lines above. bash install.sh --aur-route prints these steps without changing anything.

Install from the USB stick

The stick starts the whole bromigOS desktop before anything is installed, and installs it from there with no network. The Download page has these same steps with pictures. Each step starts with the plain way; From a terminal is the same step by hand.

1. Download it

Download the newest image from the Download page. It’s one file of about 5 GB.

From a terminal. Every release’s image is at https://pkgs.bromigos.org/iso/<version>/bromigos-<version>-x86_64.iso, beside its .sha256, .sig and .json. https://pkgs.bromigos.org/iso/latest.json names the newest; https://pkgs.bromigos.org/iso/edge/latest.json the weekly edge build. The newest three releases are kept.

url=$(curl -fsSL https://pkgs.bromigos.org/iso/latest.json | jq -r '.isos[] | select(.edition == "bromigos") | .url')
curl -fLO "$url" -fLO "$url.sha256" -fLO "$url.sig"

2. Check it (optional)

The Download page shows the image’s SHA-256 checksum. On Windows, PowerShell’s Get-FileHash .\bromigos-<version>-x86_64.iso prints it; on a Mac, shasum -a 256 bromigos-<version>-x86_64.iso. The two must match.

From a terminal. The checksum, then the signature by bromigOS’s key, whose fingerprint is 393E 7D54 F7DE 58FE 75B9 7214 947C 9D61 93D3 DD8B:

sha256sum -c bromigos-<version>-x86_64.iso.sha256
curl -fsSLO https://pkgs.bromigos.org/bromigos/bromigos.asc
gpg --show-keys --with-fingerprint bromigos.asc
gpg --import bromigos.asc
gpg --verify bromigos-<version>-x86_64.iso.sig bromigos-<version>-x86_64.iso

3. Make the USB stick

You need a USB stick of 8 GB or more. Everything on it is erased.

• Windows: Rufus. Choose the stick, then SELECT the image. Keep the partition scheme GPT and the target system UEFI. Press START, and when Rufus asks how to write an “ISOHybrid image”, choose Write in DD Image mode. balenaEtcher works too: Flash from file, Select target, Flash.
• macOS: balenaEtcher, the same three steps. When it’s done, macOS may say the disk isn’t readable: that’s expected, choose Eject.
• Linux: balenaEtcher, or GNOME Disks (Restore Disk Image).
• Ventoy: copy the .iso onto a Ventoy stick, like any other image.

From a terminal. It’s an isohybrid image, for BIOS and UEFI alike, so it goes on the whole device as it is. Find the stick with lsblk (here /dev/sdX; the wrong device erases that disk):

sudo dd if=bromigos-<version>-x86_64.iso of=/dev/sdX bs=4M status=progress oflag=sync
# or: sudo cp bromigos-<version>-x86_64.iso /dev/sdX && sync

There’s no netboot image: the medium carries an offline copy of every package an install needs, which is most of its size.

4. Start the computer from the stick

Plug it in, restart, and tap the computer’s boot menu key as it starts, then choose the stick (on UEFI computers, “UEFI: “ and its name). Common keys: Dell F12; HP Esc, then F9; Lenovo F12; ASUS F8 or Esc; Acer F12; MSI F11; Gigabyte F12; ASRock F11; Microsoft Surface: hold Volume Down while you press Power. From Windows, any brand: Settings, System, Recovery, Advanced startup, Restart now, then Use a device.

The stick’s boot menu comes up:

From a terminal, or rather the menu’s own editor: press e on an entry in GRUB (UEFI), or Tab in the BIOS menu, to change its kernel line. The entries share archiso’s line (archisobasedir=arch archisosearchuuid=… splash quiet); Install bromigOS adds bromigos.install, which opens the installer at login, safe graphics adds nomodeset, the screen reader accessibility=on. archiso’s own options work too, such as copytoram to run from memory and free the stick, or cow_spacesize=4G for more room for changes in the live session. The boot menu describes every entry.

Secure Boot

Most Windows computers have Secure Boot on. The stick starts with it on: the first time, on each computer, you enroll bromigOS’s key once, in a blue screen called MokManager. Use the arrow keys and Enter; the mouse doesn’t work there.

1. ERROR: Verification failed: (0x1A) Security Violation. Press Enter.

   

2. Shim UEFI key management: Press any key to perform MOK management. Press any key within ten seconds.

3. Choose Enroll key from disk.

   

4. Choose the stick, ARCHISO_EFI.

5. Choose ENROLL_THIS_KEY_IN_MOKMANAGER.cer.

   

6. Choose Continue (View key 0 shows the certificate first).

7. Enroll the key(s)? Choose Yes.

8. Choose Reboot, and choose the stick again in the boot menu if Windows starts.

With Secure Boot on, the stick’s menu is plain text instead of the themed one; the entries are the same. The installed system can’t start with Secure Boot on yet: after installing, turn Secure Boot off in the computer’s setup (often F2, F10, F1 or Del as it starts; from Windows: Advanced startup, Troubleshoot, Advanced options, UEFI Firmware Settings), under Boot or Security, then save and exit. If Windows uses BitLocker, have its recovery key ready first (aka.ms/myrecoverykey).

From a terminal. The chain is firmware (Microsoft’s keys) → shim 16.1, Fedora’s Microsoft-signed build, pinned by checksum → GRUB, signed with bromigOS’s key → the kernel, signed with the same key. GRUB runs in lockdown, which is why its theme’s fonts don’t load. The certificate is at the stick’s root and in the repository (iso/secureboot/bromigos-secureboot.crt; SHA-1 5F:EC:1D:6C:E1:8B:6B:D3:B9:6E:ED:E9:87:AE:B4:E9:EE:62:49:86, as MokManager’s View key 0 shows it). Memtest86+ and the UEFI shell are unsigned, so they don’t start with Secure Boot on. If you run your own keys with sbctl, enroll bromigOS’s certificate in db instead of MokManager, or sign the installed system yourself. The project’s docs/secureboot.md has the details.

5. Try it, then install

1. In the boot menu, choose Install bromigOS. Or choose Start bromigOS (try it live) to look around first: a welcome card offers Try bromigOS or Install bromigOS, and the desktop’s INSTALL panel opens the installer whenever you’re ready.

2. Follow the installer. You can go back and change anything until you press Install. It asks:

   • your language and time zone. No network is needed: everything is on the stick.

   • what kind of computer this is: bromigOS (desktop) for a computer you sit at, or bromigOS Server, with no desktop, for servers and lab machines.

   • your keyboard, with a box to try it in.

   • where to install. Choose the disk, then either:

     

     • Install alongside Windows (or the other system it found). Windows and its files stay. If there isn’t free space, the installer makes Windows’ part of the disk smaller; a slider sets how much each gets. Every time the computer starts, you choose which system to use. If it can’t be offered, the screen says why and what to do, for example turning off Windows’ Fast Startup.
     • Erase the whole disk. Everything on the disk is deleted, and the screen says what that is.

   • your name, user name, password, and a name for the computer.

   • whether to encrypt the disk. It’s on by default. Your password unlocks it when the computer starts, or you can give it a passphrase of its own.

     Remember the password or passphrase. Nobody can recover it. Without it, the disk can’t be read.

   • for bromigOS Server: whether to turn on SSH (signing in from another computer), the firewall, and automatic updates.

3. Check the summary, then press Install (or Erase disk and install). A progress bar shows how far it has got. It takes about ten minutes.

   

4. Press Restart now, and take out the stick when the screen goes dark. Type the disk’s passphrase if you chose encryption, then sign in. With Secure Boot on, turn it off first (above): the installed system can’t start with it on yet. The installer’s Before you start step reminds you.

If Windows on the disk uses BitLocker, the installer first asks you to save its recovery key, because Windows may ask for it once after the install. If something goes wrong, the installer says what to do, and Save a problem report puts the details on a USB drive for whoever helps you.

No picture, or a computer with only a text screen? Choose Install bromigOS (text mode) in the stick’s menu. It’s the same installer, with the same steps, in text. With Start with the screen reader (speech), the installer asks its questions one at a time, read aloud.

Every step, alongside Windows, reinstalling and the text installer are explained in The installer.

Installing many computers? An answer file on the stick installs with no questions (answer files).

At your first sign-in, the welcome tour opens: Wi-Fi, your screens, a world, VECTOR, your lab, your phone and the keys worth knowing. Every step has Skip.

For power users: each tour step writes the same answers as bromigos setup; see First run.

The installed system updates from the package repository the stick was made for. The boot menu’s other entries are described in The boot menu.

How the image is made

Every release’s image is built by CI from the release’s tag: archiso’s releng profile with bromigOS laid over it, and an offline repository of every package an install needs. It’s checked (the privacy guard, no keys, no proprietary packages), tested in QEMU with KVM (an encrypted UEFI install with its first update and rollback, an offline BIOS install, and Secure Boot with the MokManager enrollment), signed and published (iso.yml, docs/iso.md). To build one yourself, with Docker and about 20 GB free:

git clone https://github.com/bromigos-org/bromigOS && cd bromigOS
iso/build.sh --repo https://pkgs.bromigos.org --channel stable --out ~/bromigos-iso
iso/ci-test.sh ~/bromigos-iso/bromigos-*-x86_64.iso --out ~/bromigos-iso/tests   # needs /dev/kvm

Next

• First run: the questions bromigOS asks.
• Getting around: what’s on the screen, and the first keys to learn.

The installer

The bromigOS USB stick has one installer in two forms. The graphical installer opens full screen on the live desktop. The text installer runs on a plain text screen, for a computer whose picture doesn’t come up, a serial console, or a screen reader. Both ask the same questions in the same words, and both install the same way.

Nothing on any disk changes until you press Install on the last screen. Until then you can go back and change anything.

Starting it

• In the stick’s boot menu, choose Install bromigOS. The live desktop starts with the installer already open.
• Or choose Install bromigOS (text mode) for the text installer. There’s no desktop.
• Or choose Start bromigOS (try it live) to look around first. A welcome card offers Try bromigOS or Install bromigOS. Later, the desktop’s INSTALL panel or “Install bromigOS” in the app launcher opens the installer.

On a computer with no working graphics, “Install bromigOS” opens the text installer by itself.

The steps

1. Welcome. The language your new system uses, your time zone, and whether you’re online. You don’t need the internet: everything is on the stick.

2. Before you start. Shown only when there’s something to know: running on battery (plug in the charger), less than 4 GB of memory, a disk that reports it’s failing, a graphics card bromigOS can’t drive well, Secure Boot. Each line says what to do. None of them stops you. With Secure Boot on, install as usual, then turn Secure Boot off in the computer’s setup before you start bromigOS from the disk: the installed system can’t start with it on yet (Download page).

   

3. What kind of computer is this? bromigOS (desktop) for a computer you sit at. bromigOS Server has no desktop, for servers and lab machines.

   

4. Your keyboard. Pick the layout that matches your keys. Try it in the box.

5. Where to install. Every disk, with its size, model and what’s on it. Pick one, then choose how:

   • Install alongside Windows (or the other system it found). Windows and its files stay. You choose which system to start each time the computer starts. If there isn’t enough free space, the installer makes Windows’ part of the disk smaller. A slider sets how much each gets. Windows keeps what it uses now plus 10 GB to grow, and bromigOS gets at least 20 GB.
   • Erase the whole disk. Everything on the disk is deleted. The screen says what that is.
   • Reinstall bromigOS and keep my files, when bromigOS is already on the disk. You get a fresh system, and your home folder stays as it is.

   

6. Save Windows’ recovery key, only when Windows uses BitLocker (below).

7. About you. Your name, a user name for signing in, a password, and a name for the computer. The user name and computer name are suggested from your name.

8. Encryption. On by default. The disk can only be read after the passphrase is typed when the computer starts. By default your password is the passphrase. You can give the disk its own instead.

   Remember it. Nobody can recover a forgotten passphrase, and the disk can’t be read without it.

9. Remote access and protection, for bromigOS Server only: SSH (signing in from another computer), the firewall, and automatic updates. See bromigOS Server.

10. Summary. Every choice in plain words. The button says Install, or Erase disk and install when the disk is erased.

    

11. Installing. A progress bar and a line saying what’s happening. Details shows every step. It takes about ten minutes.

12. Done. Press Restart now. Take out the stick when the screen goes dark.

    

Installing alongside Windows

The installer won’t change Windows’ drive when that isn’t safe. It says so, and what to do:

• Windows is paused (Fast Startup or hibernation). Windows didn’t really shut down, so its drive can’t be changed safely. In Windows, open Control Panel › Power Options › Choose what the power buttons do. Click “Change settings that are currently unavailable” and untick Turn on fast startup. Then hold Shift while you click Shut down. Start the installer again.
• Windows wants to check its drive. Start Windows, let it finish starting, then hold Shift while you click Shut down.
• Windows uses BitLocker (Device encryption). The installer never makes a BitLocker drive smaller. Either turn BitLocker off in Windows (Settings › Privacy & security › Device encryption) and wait until it’s done, or make free space yourself: in Windows, open Disk Management, right-click the C: drive, choose Shrink Volume and leave at least 20 GB free. bromigOS then installs in that free space.

After installing beside Windows, Windows checks its drive once the next time it starts. That’s normal.

BitLocker’s recovery key

When Windows uses BitLocker, the installer first asks you to save its recovery key. Installing bromigOS changes how the computer starts, and Windows may then ask for that key once. Without it, Windows’ files can’t be opened.

To get it: in Windows, open Settings › Privacy & security › Device encryption › BitLocker drive encryption › Back up your recovery key. Or sign in at aka.ms/myrecoverykey on another device. The key is 48 digits. Keep it somewhere that isn’t this computer, then turn on I’ve saved the BitLocker recovery key.

Reinstalling and keeping your files

When the disk already has bromigOS, Reinstall bromigOS and keep my files gives you a fresh system and keeps your home folder: your documents, pictures, settings and everything else in it. The old system is kept as a snapshot, so nothing is lost. If the disk is encrypted, type the passphrase you use when the computer starts. The disk keeps it. If the reinstall stops partway, your old bromigOS is put back as it was, and the computer starts as before.

bromigOS Server

bromigOS Server has no desktop. It starts to a text screen and you manage it there or from another computer. The installer asks three more things:

• SSH lets you sign in from another computer on your network. It’s off by default. When it’s on, Keys only is the safe choice: you sign in with a key file from your other computer, which nobody can guess. The installer reads keys from the stick’s fieldkit folder (any .pub file), or you can paste one. Keys or my password also allows your password, which anyone on the network can try to guess.
• Firewall. On by default. It blocks connections from other computers, except SSH when it’s on.
• Automatic updates. On by default. Security fixes install by themselves, each after a snapshot, so a bad update can be undone from the boot menu.

When something goes wrong

The installer says what stopped and what to do, in plain words. Save a problem report puts the install’s logs, a summary of the hardware and your answers (never your password) on a USB drive, and says where it went. Send that file when you ask for help.

Keyboard only and screen readers

Every step works with the keyboard alone:

Every control has a hint. In the graphical installer it shows when you hover over the control, and a screen reader (Orca) reads it. In the text installer the line at the bottom of the screen says what the focused control does.

With the stick’s Start with the screen reader (speech) entry, the text installer asks its questions one at a time as plain lines, which the screen reader reads in order.

For power users

Everything below is optional. The plain steps above are the whole install.

What runs

The installers write your answers to a file only root can read and run:

sudo bromigos-iso-install --answers FILE

That turns the answers into archinstall’s two files with /usr/local/lib/bromigos-iso/answers.py: config.json and creds.json, created with mode 0600. The password and the disk passphrase go in creds.json only, never in the config, on a command line or in a log. Then it runs archinstall silently, sets up bromigOS in the new system, and prints its progress. You can also run archinstall’s files yourself:

python3 /usr/local/lib/bromigos-iso/answers.py --answers FILE --out DIR
sudo bromigos-iso-install --config DIR/config.json --creds DIR/creds.json

--menu (with --config) opens archinstall’s own menu, filled in, so you can change anything before it installs. The install’s log is /var/log/bromigos-iso-install.log on the live system. The installed system keeps your answers, without the password and passphrase, in /var/log/bromigos/install-answers.toml: add a password and it’s an answer file that repeats the install.

Show what will run and Advanced. Both installers have a Show what will run toggle on the summary. It shows the archinstall configuration with every secret replaced by ********, and the bromigos setup lines the install will run. The Advanced expander on the Where step, out of the way unless you open it, offers custom partitioning (archinstall’s own partitioning menu), the root’s file system options, swap (zram by default), the kernel (linux, linux-lts or linux-zen) and the boot loader. The shell key (Ctrl+Alt+T in the graphical installer, F12 in the text installer) gives you a root shell on the live system at any step.

Answer files

An answer file installs with no questions. After a 10-second countdown with Cancel, the install runs by itself. A file with problems is never half-used: the installer says what’s wrong and asks the questions instead.

The installer looks for one:

1. at bromigos.answers=PATH on the kernel line: a file on the live system, or a path on the stick;
2. else at bromigos/install.toml or fieldkit/install.toml on a USB drive: a partition formatted FAT, exFAT or NTFS, or a stick formatted without a partition table.

Flat YAML (install.yaml, one key: value per line) works too.

Erase a disk, encrypted, for the desktop:

[install]
edition = "desktop"
locale = "en_GB"
timezone = "Europe/London"
keyboard = "gb"
disk = "/dev/nvme0n1"
mode = "erase"
full_name = "Alex Rivera"
user = "alex"
hostname = "alex-pc"
password = "correct horse battery staple"
encrypt = true

Beside Windows, giving bromigOS 128 GiB:

[install]
edition = "desktop"
locale = "en_US"
timezone = "America/Chicago"
keyboard = "us"
disk = "/dev/nvme0n1"
mode = "alongside"
bromigos_bytes = 137438953472
user = "sam"
hostname = "sam-laptop"
password = "a long passphrase you will remember"
encrypt = true
separate_passphrase = true
passphrase = "a different one for the disk"
bitlocker_saved = true
countdown = 30

bromigOS Server, keys only:

[install]
edition = "server"
locale = "en_US"
timezone = "UTC"
keyboard = "us"
disk = "/dev/sda"
mode = "erase"
user = "ops"
hostname = "rack-01"
password = "used at the console and for sudo"
encrypt = true
ssh = true
ssh_password = false
ssh_keys = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI…your-key… you@laptop"]
firewall = true
auto_updates = true
countdown = 10

Boot parameters

When the text installer is asked for on the full stick, the login screen steps aside for that boot so the installer has the screen.

The disk layout

Erase:

Alongside: the disk’s own EFI system partition (Windows’) is mounted at /boot/efi, untouched apart from GRUB’s own folder. A new 2 GiB ext4 /boot and the btrfs root go in the largest free stretch. /boot‘s partition type is set back to “Linux filesystem” after archinstall, so the disk keeps one EFI system partition. GRUB goes in EFI/GRUB with a firmware boot entry first in the boot order, not at the removable path EFI/BOOT/BOOTX64.EFI, which is Windows’ fallback loader. GRUB_DISABLE_OS_PROBER=false in /etc/default/grub makes every grub-mkconfig list Windows; the menu waits 10 seconds.

On a BIOS computer the disk must use MBR (GPT needs UEFI), and MBR holds four partitions: alongside needs two free slots. On a UEFI computer the disk must use GPT.

btrfs subvolumes: @ (/), @home (/home), @log (/var/log), @pkg (/var/cache/pacman/pkg) and @.snapshots (/.snapshots). snapper keeps snapshots of / and /home; GRUB lists the root’s snapshots (grub-btrfs).

LUKS: LUKS2 around the root partition only. The passphrase is your password unless you gave the disk its own. archinstall adds the encrypt hook and the kernel parameter; the installer adds plymouth before it, so the passphrase prompt is part of the boot splash. /boot stays unencrypted: GRUB reads the kernel from it, and GRUB can’t open a LUKS2 volume protected the way archinstall makes it. Your files, the system and the snapshots are all inside the encrypted part.

How alongside makes room

When there’s 20 GB or more of free space, nothing is resized. Otherwise the biggest NTFS (or ext4) partition with room to spare is shrunk, after checking again that it isn’t BitLocker, hibernated or waiting for a check:

1. the file system first: ntfsresize (or e2fsck and resize2fs for ext4), a dry run, then the real one;
2. then the partition: sfdisk -N, a little larger than the file system;
3. then a check that the file system still reads whole (ntfsresize --info).

The resize marks the NTFS volume for Windows’ own check, so Windows runs it once at its next start.

How reinstall works

1. The root is unlocked (LUKS) with the passphrase you typed.
2. The old @ is kept as a read-only snapshot, @old-root-DATE, and @.snapshots becomes @old-snapshots-DATE. A fresh @ and @.snapshots are made. @home, @log and @pkg are kept.
3. Everything is mounted at /mnt and archinstall installs into it (its pre-mounted layout).
4. The people from the old system come back with the same user IDs, groups and passwords (from the old /etc/passwd and /etc/shadow); you get the new password. /home’s snapper configuration comes back too.
5. The disk’s unlocking and GRUB are set up again. Only then are the old kernels, kept aside on /boot until now, removed.

If the install stops before step 5 finishes, the old system is put back: @ again from @old-root-DATE (its fstab naming the subvolume by name), its snapshots and its kernels. The computer starts as it did before, and the installer says so.

To look at the old system later, mount the btrfs volume with subvolid=5 and open @old-root-DATE. Delete it with btrfs subvolume delete when you no longer need it.

More detail, for contributors, is in the repository’s docs/iso.md.

First run

At the end of the install, bromigOS asks a few questions in the terminal: your monitors, the theme, where VECTOR’s thinking runs, and so on. Most questions have a sensible answer already chosen, so you can press Enter. The Homelab question starts on Skip. To look for your homelab’s machines, choose Find my lab. It runs after the questions, and asks before it reads anything (Find my lab). If you have a settings file for your homelab, choose Use a homelab.toml, then press Tab to type its path. You can change any answer later.

If you installed from the bromigOS USB stick, the questions were answered for you (the Wick theme, with VECTOR’s brain, voice and creation tools off), and your first login opens the welcome tour instead.

The welcome tour

A full-screen walk through the things worth setting first. Every step has Skip, and nothing changes until you press Continue on it:

1. Wi-Fi, only when you’re not connected: pick a network and type its password.
2. Your screens: which one is the main screen. Arrange and sizes… opens Settings › Displays.
3. A world: the themes as pictures. Click one and Continue puts it on.
4. VECTOR: where his brain runs (not yet, a local Ollama on this computer, or a service you name) and his voice (off, Kokoro on the processor, or the designed voice on the graphics card). A voice downloads its model once, in a window that shows how far it’s got.
5. Your homelab, if you have one: Find… looks for it and asks before it reads anything, or Choose… a homelab.toml you already have.
6. The keys: Super+Space, Super+Enter, Super+, and a few more. Press one and its card lights up.
7. Done: what you chose.

Each step runs the same bromigos setup section you could run yourself, so the tour and bromigos setup never disagree. To take the tour again, open Settings › About › Welcome tour, or run bromigos welcome.

The first time you log in, a notification offers ready-made layouts for your panels: Minimal, Developer, Homelab and more, each fitted to your screen and your theme. They’re in Customize, on the Widgets tab (Layouts).

Answer the questions

Each question is a page with a list of choices.

At the end, a review page lists your answers. Press Enter to apply them.

The questions

The cloud costs money. The suggested order for AI work leaves the paid cloud out, unless this machine has nothing else that can do the work. Check the order on the review page before you press Enter.

Change an answer later

To ask one question again, run bromigos setup with the section’s name. Your other answers stay as they are. For example, to change VECTOR’s voice:

bromigos setup voice

The sections are monitors, aur, hardware, accessibility, theme, vector, voice, homelab, targets, create and peripherals. Run bromigos setup on its own to answer them all again.

You can also open the menu with Super+Space and choose SETUP. Each question is an item there. Most answers are in Settings too.

Set up many machines the same way

To install without questions, write the answers in a file and pass it to setup:

bromigos setup --answers answers.toml

Or give answers as options, such as bromigos setup --theme mire --voice off. The file’s format is in the developer docs, docs/install.md, and bromigos setup --help lists every option.

Where your answers go

Most answers are saved as your own settings, in ~/.config/bromigos/ and in your ~/.config/hypr/hyprland.lua. The theme you pick is kept in ~/.local/state/bromigos/theme/. See Files and folders.

The welcome tour

The first time you sign in after installing from the bromigOS USB stick, a short tour opens full screen. It walks you through the things worth setting first. Every step has Skip, and nothing changes until you press Continue on it.

To take the tour again: Settings › About › Welcome tour, or run bromigos welcome.

The steps

1. Wi-Fi, only when you’re not connected. Pick a network and type its password.

2. Your screens. Which screen is the main one: the live background and the panels go there. Arrange and sizes… opens Settings › Displays.

3. A world. The themes, as pictures of the desktop wearing them. Click one to put it on.

   

4. VECTOR, your desk’s AI. Choose where his brain runs:

   • Your lab: your homelab’s model server, found on the next step (or the one you already connected).
   • This computer: only offered when your graphics card has 8 GB of memory or more. The tour shows the model the lab catalog picks for your card and how much it downloads. It installs what’s needed through the system’s own password prompt, in the window: no terminal.
   • A service: any OpenAI-compatible server you name, with its address, model and a file holding its key.
   • Not now: he waits until you give him one.

   When the brain works, VECTOR says hello in the window, and out loud if he has a voice. His voice is the second choice: off, Kokoro (runs on the processor), or the designed voice (needs a graphics card). A voice downloads its model once; the window shows how far it’s got.

   

5. Your lab, all in the window:

   • Find looks for your lab on your network. It only reads what this computer already knows (devices that announce themselves, its list of nearby devices, your Tailscale devices); it never scans. It lists each lab machine with what it offers, such as models and services. Nothing is written until you press Connect.
   • I have a lab connection file: pick a homelab.toml, or the lab connection from a Field Kit stick.
   • Make this computer my lab: only with a capable graphics card. It shows bromigos-lab’s reviewed plan for this computer before anything happens.
   • Skip.

   Problems are said in plain words, with what to do.

   

6. Pair your phone with the BRODEC app: see Pair your phone.

7. The keys. Super+Space, Super+Enter, Super+, and a few more. Press one and its card lights up.

8. Done, with what you chose.

Every step works with the keyboard alone: Tab moves, Enter continues, Esc goes back. Every control has a hover hint, which a screen reader reads too.

bromigOS Server

bromigOS Server’s tour runs in the terminal at your first sign-in, at its console or over SSH (bromigos welcome-console). It has the same steps without the desktop ones: the network, SSH, VECTOR, your lab, pairing your phone, and a short tour of what’s on the server. The pairing QR code is drawn in the terminal at 80×24 and bigger; on a smaller window it shows the short code and asks you to make the window bigger for the QR.

For power users

Every choice in the tour is one bromigos setup command, the same one you can run yourself. The tour keeps no settings of its own.

To script the whole tour, run those commands in order, or put the answers in a file: bromigos setup --answers FILE takes the same TOML the installer’s first-run answers use (First run). The hello test is bromigos-holo ask "Say hello".

The tour opens once because the installer leaves ~/.local/state/bromigos/welcome-pending; the session’s autostart runs bromigos welcome --if-pending, which does nothing without it. Finishing removes the file and writes what you chose to ~/.local/state/bromigos/welcome.json. bromigos welcome --step STEP opens it on one step; bromigos welcome --render DIR draws every step to pictures and exits.

Pair your phone

With the BRODEC app on your phone paired to this computer, you can reach it from anywhere. The welcome tour’s Pair your phone step sets it up, and you can do it again any time.

Get BRODEC

BRODEC is on Google Play (org.bromigos.brodec): the tour shows a QR code that opens it. BRODEC for iPhone is coming.

Pair

1. BRODEC’s helper. Pairing uses BRODEC’s machine helper, brodec-machine. The step explains it and installs it when you agree, the usual way: the system asks for your password in its own window. No terminal. The same password lets the helper run on this computer (Allow pairing, if it was installed some other way).
2. Scan the code. The step shows a big QR code and a short code. In BRODEC, open LAB › MACHINES › ADD MACHINE and scan the QR, or type the short code. A code runs out after a few minutes; the next one appears by itself.
3. Confirm on your phone. BRODEC shows this computer’s name and asks you to confirm. When it’s done, the step ticks ✓.
4. Let your phone run things here (optional). Restarting, updating and terminal sessions from the phone also need your say-so at this computer. In BRODEC, open LAB › MACHINES › this computer › ALLOW THIS PHONE, then press Allow… in the step. It asks for your password and shows the phone’s key: compare it with the one on the phone, then Allow.

If this computer runs your lab’s VECTOR bridge (brodec-lab), the step offers to pair it too: Pair it asks for your password and shows the bridge’s own code.

On bromigOS Server the same step runs in the console tour: the QR is drawn in the terminal, and sudo asks for the password where the window would.

What your phone can do then

• Chat with VECTOR, from anywhere.
• Approve the fixes VECTOR proposes for this computer.
• Restart, shut down or update this computer.
• Open chat-style terminal sessions on it.

Nothing runs on this computer without your say-so: everything travels end-to-end encrypted, from your account only, and the serious requests ask for your fingerprint on the phone.

For power users

The helper is brodec-machine, a user service (brodec-machine.service). It runs only once root’s /etc/brodec-machine/machine.toml exists; the step writes it from the packaged example (/usr/share/brodec-machine/machine.toml.example) through polkit. On a desktop the helper comes in brodec-desktop; a server gets the separate brodec-machine package when the repository has it.

A code event carries the QR’s text (qr), the QR drawn as SVG (qr_svg, the window’s) and as terminal text (qr_text, the console’s), and the code to type (user_code_display). Leaving the step stops only the watching (SIGTERM): the agent keeps offering codes, so pairing later still works. Pairing is the Bromigos account’s device flow, approved from the phone with kind: "machine"; the phone checks the machine’s key against the fingerprint in the QR, so one scan verifies both ways. BRODEC’s own description is its docs/MACHINE_JOBS.md, “Pairing from a setup screen”.

Getting around

This page shows what’s on the screen, the keys to learn first, and how to open apps, lock the screen and log out.

What’s on the screen

1. The bar, along the top. It shows your workspaces, the window you’re in, what’s playing, and readings such as processor use and the clock. Click its parts to act on them. See The bar, below.
2. The panels, on the left of your main monitor. They show live readings and your notes, under your windows. See Panels.
3. Your windows, such as this terminal. They tile: each new window takes a share of the screen, and nothing overlaps unless you ask. See Windows and workspaces.
4. The background. In the default theme it’s the den, a radio room whose screens and meters move with your machine’s readings. Other themes bring other scenes. See Themes and worlds.

Hover over anything on the bar or the panels. It says what it is and what it does.

The keys to learn first

Super is the key with the Windows or logo symbol on it.

The keys for windows use Alt, and so do everyday ones such as the launcher, the terminal, screenshots and the power menu. bromigOS’s other keys use Super. To change any key, see Your own shortcuts.

To search the keys by name, press Super+Shift+K, type, and press Enter to run the one you pick. Every key is listed in Keys.

Open an app

• Press Alt+P, type part of the app’s name, and press Enter.
• Or press Super+Space and type. The menu finds apps, settings and bromigOS’s own tools.
• Or click the emblem at the left end of the bar.

bromigOS’s own windows are in the launcher too, each with its own icon: bromigOS Settings, Theme Switcher, Shortcuts, Extensions, Update bromigOS and the holograms.

To keep a website as an app of its own, see Web apps.

The bar

From left to right:

To hide the bar, press Alt+B. Press it again to bring the bar back.

The sound popup

Rest the pointer on the volume for a moment and the sound popup opens under it. It closes when the pointer has left both the volume and the popup. Click the volume, or anywhere in the popup, to keep it open. Then Esc, a second click on the volume, or a click anywhere else closes it. A click elsewhere still reaches what you clicked.

• OUTPUT lists your speakers, headphones, screens with speakers (HDMI or DisplayPort) and Bluetooth headphones. The one in use says IN USE. Click another to switch to it: what’s playing moves there.
• INPUT lists your microphones the same way.
• Each has a volume slider and MUTE.
• Bluetooth headphones show whether they’re in HI-FI or HEADSET + MIC, and the codec. Bluetooth explains both.
• OPEN AUDIO SETTINGS → opens Settings › Sound, with each app’s volume and the desktop’s own sounds.

(bromigos sound popup)

Wine tray icons

Battle.net, Wine apps and older X11 apps appear in the bar’s tray, with their mouse menus. bromigOS starts a bridge at login. If an app already has its own floating tray, close that app and open it again after logging out and back in following an update.

Notifications

Notifications appear in a corner of the screen and go after a few seconds. Critical ones stay until you close them. To stop them for a while, turn on Do not disturb in Settings › Notifications, or run bromigos notifications dnd on. The same page sets which corner they use and how long they stay.

Sound

The volume keys on your keyboard work as usual. The desktop also makes its own sounds: short cues from the theme, and VECTOR’s voice. To mute those and leave your apps alone, press Super+Shift+M. Press it again to unmute.

To choose your speakers or microphone, open Settings › Sound.

Lock, log out and shut down

The screen also locks by itself when you leave the computer for a while. See Idle and lock to change when, or to stop it.

Next

• The menu: everything bromigOS does, in one place.
• Windows and workspaces: moving, resizing and arranging windows.
• Common tasks: step-by-step answers to everyday jobs.

The menu

The menu is one place for everything: your apps, your settings, the themes, updates and every bromigOS command. If you don’t know where something is, start here.

Open the menu and find something

1. Press Super+Space.
2. Type a few letters of what you want, such as theme, update or firefox. The menu searches every group at once.
3. Press ↑ or ↓ to choose, and Enter to run it.

Press Esc to close the menu without running anything.

You can also browse. The first screen lists the groups. Choose one to see only its items, and choose ‹ BACK to return.

Items that need a terminal, such as an update or a setup question, open one. The terminal stays open afterwards, so you can read what happened.

What’s in each group

The TOGGLE group shows each switch’s state, such as Reduced motion: off. Choosing it flips the switch, and the menu stays open so you can flip another.

The menu updates itself

The menu is built from what’s installed each time it opens. A new app, extension or command of your own appears in it the next time you open it.

To print the whole menu in a terminal, run:

bromigos menu --dump

The app launcher

The app launcher (Alt+P) is simpler: it lists apps only. bromigOS’s own windows are in it too, with their own icons:

• bromigOS Settings, Theme Switcher and Extensions;
• Shortcuts, to change a key, and Key List, to see them all;
• Update bromigOS, which runs the update in a terminal that stays open;
• the holograms: Holo Deck, Drift Map, Timeline, Swarm, Lab Deck, Ops Theater, Network Map and Mind. The homelab’s decks fill in once you connect your homelab;
• Screensaver, Desktop Panels, Field Notes, Lab Console and Power Menu;
• bromigOS Menu, which opens the menu above;
• with VECTOR installed, VECTOR and Hologram Gallery.

Type a word such as theme, deck, keys, update or lab to find them. Opening a hologram or the panels from the launcher always shows them. It never closes one that’s already open.

Add your own items

A command you write appears in the menu’s COMMANDS group. See Your own commands.

Windows and workspaces

bromigOS arranges windows for you. Each new window gets a share of the screen, and no window hides another unless you let it float. You move between windows and workspaces with the keyboard, or with the mouse if you prefer.

The window keys use Alt. If you’d rather use Super, see Use Super for the window keys.

How windows are arranged

The first window takes the large space on the left. Each new window goes to the top of the stack on the right. Close a window and the rest grow to fill the space.

Pointing at a window with the mouse also moves you to it. To change that, open Settings › Keyboard & input and choose another Window focus.

Use the mouse

• To move a window, hold Alt and drag it with the left mouse button.
• To resize a window, hold Alt and drag it with the right mouse button.

Make a window bigger

Press the same keys again to put the window back.

Let a window float

A floating window sits above the others, at any size, like on most desktops. Dialog boxes float on their own.

To float the window you’re in, press Alt+Shift+V. Press it again to put the window back in the tiles.

Put floating windows back where you left them

bromigOS can remember where you put a floating window, for each workspace, and put it there the next time it opens.

1. Open Settings › Startup.
2. Under Windows put back, turn on Every floating window. Or type one app’s class in Remember an app (its class), such as org.pulseaudio.pavucontrol for the volume mixer.
3. Choose Restart on the bromigos-windows row, or log in again. The change works from then on.

To find an app’s class, run hyprctl clients in a terminal while the app is open.

Or from a terminal:

bromigos startup windows remember org.pulseaudio.pavucontrol   # remember this app's windows
bromigos startup windows restart                               # use the change now
bromigos windows list                                          # what's remembered
bromigos windows clear                                         # forget them all

Workspaces

A workspace is a separate screenful of windows. There are ten. Use them to keep tasks apart: a browser on one, your project on another.

Sending a window doesn’t move you with it. The bar shows the workspaces that have windows. Click one to go there.

On a laptop, swipe sideways with three fingers on the touchpad to move between workspaces.

With more than one monitor

The ten workspaces are shared out across your monitors, from left to right. With two monitors, workspaces 1 to 5 are on the left one and 6 to 10 on the right one. Pressing a workspace’s key takes you to the monitor it’s on.

To choose which workspaces go on which monitor, see the workspaces setting in your ~/.config/hypr/hyprland.lua. The file’s comments show the format.

The scratchpad

The scratchpad is a hidden workspace that opens over the one you’re on. It’s handy for a terminal or notes you want now and then.

Switch windows from a list

Press Alt+Tab for a list of every open window. Type to filter it, and press Enter to go to the one you pick.

Common tasks

Step-by-step answers to everyday jobs. Each one links to the page with more detail.

Most settings live in Settings, which opens with Super+, (Super and the comma key). In Settings, start typing to search for any setting.

Apps and windows

Open an app

1. Press Alt+P.
2. Type part of the app’s name.
3. Press Enter.

Open a terminal

Press Alt+Shift+Enter.

Close a window

Press Alt+C.

Install an app

1. Press Super+Space and type package.
2. Choose INSTALL › Package….
3. Type the package’s name and press Enter. A terminal opens and installs it.

Or in a terminal: sudo pacman -S and the package’s name.

Keep a website as an app

1. Press Super+Space and type web app.
2. Choose INSTALL › Web app….
3. Type a name and the site’s address.

The site opens in its own window and appears in the app launcher. See Web apps.

Move a window to another workspace

Press Alt+Shift and the workspace’s number. See Windows and workspaces.

Look and feel

Change the theme

1. Press Super+Ctrl+Shift+Space. The theme switcher opens, with a picture of your desktop in each theme.
2. Choose a theme with the arrow keys, or type part of its name.
3. Press Enter. Every app changes colour within a second.

See Themes and worlds.

Turn off the animated background

Press Super+Shift+B. Press it again to turn it back on.

To keep the background but make it calmer, see the next task.

Reduce motion

1. Open Settings › Accessibility.
2. Under motion, choose Reduced for a calmer desktop, or Still for a background that doesn’t move.

See Accessibility.

Show or hide the panels

Press Super+W to show or hide all of them. To choose which panels show, open Settings › Widgets. See Panels.

Network, sound and devices

Connect to Wi-Fi

1. Open Settings › Network.
2. Choose your network from the list.
3. If it has a lock, type its password. bromigOS remembers it.

Change the volume, or switch speakers

• Use your keyboard’s volume keys, or scroll over the volume on the bar.
• To switch speakers or headphones, rest the pointer on the volume on the bar and choose one in the sound popup. Settings › Sound has the same choice.

Mute the desktop’s own sounds

Press Super+Shift+M. This mutes the theme’s sound cues and VECTOR’s voice. Your apps keep their sound.

Pair a Bluetooth device

1. Put the device in pairing mode.
2. Click the Bluetooth icon on the bar and choose SCAN.
3. Choose PAIR beside the device when it appears.

Bluetooth has the steps for an Xbox controller and for headphones.

Set up your monitors

1. Open Settings › Displays.
2. Drag the monitors in the picture to match your desk, and set each one’s resolution and scale.
3. Choose Apply. bromigOS asks whether to keep the new settings. If you don’t answer within 15 seconds, it puts the old ones back.

Change the keyboard layout

Open Settings › Keyboard & input and choose your layout. You can add a second layout and a key to switch between them.

Screen and power

Take a screenshot

• Press Alt+Y and drag out an area.
• Press Alt+Shift+Y for the whole of the monitor you’re on.

The picture goes to ~/Pictures/screenshots and is copied to the clipboard, ready to paste.

Record the screen

Press Alt+Shift+R and drag out an area. Press it again to stop. The video goes to ~/Videos/recordings.

Lock the screen

Press Super+L.

Stop the screen locking while you watch something

Click the eye on the bar. Nothing locks or sleeps for an hour. Click it again to stop. See Idle and lock.

Turn off the lock when you’re away

1. Open Settings › Idle & lock.
2. Choose Screensaver only. The screensaver still starts, but the screen doesn’t lock.

Shut down or restart

Press Alt+Shift+E and choose from the power menu.

Stop notifications for a while

Open Settings › Notifications and turn on Do not disturb.

VECTOR

Ask VECTOR something

1. Press Super+E.
2. Type your question and press Enter.
3. Press Esc to go back to your work.

To talk instead of typing, hold Super+V while you speak. See VECTOR.

Write a quick note

Press Alt+Shift+N, type one line and press Enter. It’s added to your field notes. See Panels.

Keys

Find a key

Press Super+Shift+K and type what you want to do. Press Enter to run it. See Keys.

Change a key

1. Open Settings › Shortcuts.
2. Under Every key, open the key’s section, and choose Change… next to it.
3. Press the new keys, then let go.

See Your own shortcuts.

Updates

Update bromigOS

1. Open a terminal with Alt+Shift+Enter.
2. Run bromigos update.
3. Type your password when it asks.

Undo an update

Run bromigos update --rollback. It shows what the last update changed, asks, and puts it back. See Updating and rolling back.

Your homelab

Connect your homelab

Run bromigos setup homelab. It looks for your homelab’s services and connects the ones it finds. See Your homelab.

Themes and worlds

A theme changes the look of the whole desktop at once: the colours of every app, the bar’s icons, the wallpaper, the lock screen and the boot menu. Some themes are worlds: instead of a still wallpaper, they bring a living scene that reacts to what your machine is doing.

Change the theme

1. Press Super+Ctrl+Shift+Space. The Customize window opens on its Themes tab, with a picture of your desktop wearing each theme.
2. Choose a theme with the arrow keys or the mouse. To narrow the list, type part of a name, or world or colour.
3. Press Enter, or click the theme. The desktop changes colour within a second. A few apps change the next time you open them.

Press Esc to close the switcher without changing anything. Hover over a card to read what the theme is.

Apps the theme colours

These change as soon as you choose a theme:

• the bar, the window borders, notifications and the on-screen display;
• the terminal (kitty), tmux and Neovim;
• the panels (widgets), VECTOR and the decks;
• GTK apps, and Chromium or Chrome’s window frame, if one is open;
• the shell prompt, at its next line.

These change the next time you open them:

• the app launcher and the lock screen;
• btop, Qt apps and libadwaita apps;
• Firefox and LibreWolf, in a profile set up for it (theming.md);
• Zettlr, the Markdown notes app.

Zettlr

If you use Zettlr, every theme colours it, in the desktop’s font. Close Zettlr and open it again after you change the theme. It only reads its colours when it starts.

bromigOS keeps its colours in a marked block in Zettlr’s own custom CSS. To see that file in Zettlr, choose File › Preferences › Assets Manager, then Custom CSS. Put your own rules below the block, with !important, and they stay through every theme change. bromigOS also switches Zettlr’s dark mode to match the theme. It changes no other setting of Zettlr’s.

Customize

The window you choose themes in is called Customize. It has two tabs:

• Themes, the pictures above;
• Widgets, every panel you can put on your desktop, with a switch for each, its sizes, and more to install.

Press Ctrl+Tab to change tab. In the menu, STYLE has an item for each tab. The app launcher lists it as Customize.

On the Themes tab:

• Make your own… copies the theme you’ve selected into a new theme of yours, to change as you like.
• Remove removes a theme you added. It can’t remove bromigOS’s own themes, or the one you’re wearing.
• Install from URL… adds a theme someone shared as a link.
• Wallpaper, sounds, lights… opens Settings at what goes with any theme.

You can also choose a theme in Settings › Theme, or in the menu under STYLE. Or from a terminal:

bromigos theme             # list the themes; the one in use is marked
bromigos theme set mire    # switch to Mire
bromigos theme set wick    # back to the default

The switcher draws its pictures in the background after an update, or when you add a theme. A card that’s still being drawn shows the theme’s colours and the word DRAWING. To draw any missing pictures now, run bromigos theme previews.

A few things keep the Wick’s look in every theme: the login screen and the splash screen while the computer starts.

The themes

bromigOS comes with eleven themes.

A colour theme shows the den in its own colours.

Wick · Tidewell and Wick · Mire are for when you like a world’s colours but want the den behind your windows. They’re colour themes, not the worlds: the den keeps its screens, its glyph rain and your Wick panel layout. To see the sea or the bayou, choose Tidewell or Mire.

The worlds

In a world, everything that moves shows something real. Nothing moves just for decoration. If bromigOS can’t read something, such as a homelab you haven’t connected, the part of the scene it drives isn’t drawn.

Each world has a keeper, a figure who works while you work and dozes when you leave the computer.

Mire

A night bayou.

Tidewell

The sea at night, under a lighthouse called Greywater Light.

Craft cross the sky now and then in both worlds.

Make it calmer

Both worlds can move less, or hold still like a photograph. See Accessibility.

The den TV

The den’s screens can show your own videos, like a TV that’s always on. A TV channel plays from your Jellyfin or Plex server, a YouTube playlist or channel, or a folder of videos. Whenever you look, it’s part-way through something, as if it had been on all along. It’s silent until you turn the sound on. (A TV channel has nothing to do with the update channel your machine follows.)

Every channel can play on any of the den’s three screens, and each screen plays its own channel at the same time. Channel 1 is what the screen always shows, such as the relay map on the big monitor. Your channels come after it. The hover menu appears when you point at a TV; turning Den TV off leaves the scene unchanged. Two screens on the same channel show the same moment, like real TV.

Watch it

Point at a screen that has channels. A hint shows what’s on.

From the keyboard, Super+Alt+P opens what’s on full screen, and Super+Alt+. and Super+Alt+, change channel. The keys act on the screen under the pointer. Each screen remembers its channel, its sound and its volume.

If the sound is on but you hear nothing, the hint says why, such as “Your desktop is muted”.

The TV goes quiet when you lock the screen or the screensaver starts, and when you mute everything with Super+Shift+M. It turns down while VECTOR speaks. In the sound settings it’s called bromigOS den TV.

It only plays while you can see it. With the screen locked, or behind a window while it’s silent, it pauses and costs nothing. A screen whose sound is on keeps playing behind windows, so you can listen. When it shows again, it’s where it would be by now.

The channel guide

The channel guide shows every channel once, like a TV guide: what’s on now and next, with its poster and how far through it is. Under each one, BIG, SCOPE and SMALL put that screen on it; the lit button shows where it’s on air. Open the guide with GUIDE in the hint, Super+Alt+G, or the Den TV app in the launcher. bromigos-live tv guide and the MEDIA panel’s guide button open the same app. Settings keeps playback on/off, how many screens play at once, and when a window pauses a silent screen. Its Open Den TV… button opens the guide.

Use a card’s Contents… menu to see its titles, reorder picks, or add and remove items. Shuffle, In order and Alternate choose its play order.

The den follows each change at once, without restarting. The media library and commands edit these same channels.

Add a TV channel by hand

The guide is the easiest way. The MEDIA panel’s settings make one channel too (Panels).

The channels are kept in ~/.config/bromigos-live/config.toml, and you can write them there yourself:

[[tv.channel]]
name = "Saturday"
library = "TV Shows"          # or collection = "…" or playlist = "…"

[[tv.channel]]
name = "Lo-fi"
youtube = "https://www.youtube.com/playlist?list=<id>"

Replace <id> with the playlist’s ID. The den TV reads the file when you save it.

• Jellyfin or Plex needs your server in Your homelab, with a key: a Jellyfin API key or a Plex token. The MEDIA panel tells you if the key is missing.
• YouTube: a channel’s address plays its videos. If it’s live, a second channel follows it with the live stream.
• Keep YouTube videos. Add keep = "~/Videos/YouTube" to a YouTube channel. Each video it plays is saved there, in the layout Plex and Jellyfin read, and plays offline from then on. Any folder works, a NAS share included. keep_max_gb = 50 caps it.
• Videos on your disk. files = "~/Videos/Home" plays a folder.
• Shows you pick. shows = ["Example Show", "Another Show"] plays those shows’ episodes. Shuffled, they mix. With order = "in order", they take turns, one episode of each, like an evening on a TV network. Each show goes on from where it left off, day after day. items = [...] picks movies, and collections = [...] collections.

A playlist plays in order, and anything else shuffled, the same way all day. Add order = "in order" or order = "shuffle" to choose. Every channel plays on every screen. To keep one to some screens, add screens = ["wave"] for the scope, or "emblem" for the small monitor. bumpers = true opens each item with a station card.

To start each screen on its own channel, name them:

[tv.start]
big = "Saturday"
wave = "Lo-fi"

A screen starts there until you change its channel. Then it remembers yours.

The den TV’s player (mpv) and YouTube support (yt-dlp) come with bromigOS. With the background still or on a computer without a working graphics card, it shows posters instead.

The worlds

The den TV is the den’s: the Wick and the colour themes have it. Mire and Tidewell have no screens, so they don’t.

Turn parts of the background on and off

The background is made of many small animations: rain, stars, passing ships, the flash on an urgent notification, and more. Each one has a switch.

• In the menu, open TOGGLE. Each animation is listed with its state.

• Or in Settings › Live layer & holograms.

• Or from a terminal:

  bromigos anim                 # every animation, and whether it's on
  bromigos anim off ships       # turn one off
  bromigos anim on all          # turn them all on
  bromigos anim reset           # back to the defaults
  

To turn the whole background off, press Super+Shift+B.

Theme sounds

Themes have sounds: short cues, the world’s own sounds, and spoken codec calls for important events.

• To mute the theme’s sounds and VECTOR’s voice together, press Super+Shift+M. Press it again to hear them.
• To mute only the theme’s sounds, turn off Theme sounds in Settings › Theme.
• bromigos anim off sounds also turns the theme’s sounds off.

The den wallpaper

The Wick’s background is the den. bromigOS ships one den picture. Super+Ctrl+Space steps through den pictures, so it only changes something when you’ve added den pictures of your own to ~/.config/wallpaper. A world brings its own painting, so the key does nothing there.

Get more themes

Themes that other people share are extensions.

• The theme switcher lists the catalog’s themes after yours. Choose one to install it and switch to it.

• Or open Settings › Theme and search the catalog under Get more themes, or paste a theme’s git address.

• Or from a terminal:

  bromigos theme install https://github.com/someone/their-theme
  bromigos theme remove their-theme
  

bromigos ext update --all keeps installed themes up to date.

Make your own theme

1. Run bromigos theme new dusk --from wick. This makes a folder called dusk with a copy of the Wick to change.
2. Edit its colors.toml.
3. Install it with bromigos ext install --copy ./dusk, then switch with bromigos theme set dusk.

A theme can also be a plain folder in ~/.config/bromigos/themes/, with a colors.toml in it. The full format, and how to make a world, are in the developer docs: theming.md and worlds.md.

Den TV controls

Hover over a TV to open its menu for channels, sound, volume, SKIP, FULL and GUIDE. SKIP advances the channel to its next item. Switching away and back keeps that progress, including after restarting the live layer. The channel continues playing while you watch another channel. The menu is on by default. A change shows its volume, channel or crossed-out speaker on the TV for about a second and a half. The same feedback appears for commands, VECTOR, keys and the MEDIA widget. Reduced motion uses an immediate on/off change.

To hide the hover menu, turn Floating controls off in Settings › Den TV or in the Den TV app, or run bromigos-live tv hint off. tv hint on brings it back. The config setting is [tv] hover_hint = false. The MEDIA remote, number-pad remote and Den TV app remain available. Nothing is drawn when Den TV is disabled.

The MEDIA remote has a SKIP button for the selected screen and a rotary volume dial. The dial’s label names the screen with sound. Scroll it or drag around it or up and down. Click to mute or unmute. Each screen’s row shows a speaker and percentage: click the speaker to move the sound there, or mute it; scroll over the row to change that screen’s volume. Only one screen has sound at a time.

Full screen uses its own themed mpv controls. Hover the volume icon to unfold a slider upward; scroll to change volume, or click the icon to mute. The channel buttons change what is playing, and BACK returns to the den. Audio and subtitle menus are beside the timeline. Your normal mpv settings stay separate. Volume follows you back to the screen when you close the player.

The number-pad remote

Press Super+KP 1, 2 or 3 to select BIG, SCOPE or SMALL. Its bezel lights up. While selected, the number pad controls that TV. NumLock may be on or off. Super+KP 0, Escape or fifteen seconds without a key returns the pad to its normal use. Super+KP 1/2/3 switches screens.

           / Guide       * Sound here     − Volume down
       7              8 Channel up     9          + Volume up
       4 Previous     5 Mute           6 Skip
       1              2 Channel down   3          Enter Full screen
       0 Leave remote                  . Enter channel number

Press decimal, then the channel’s digits. It tunes after a one-second pause; Enter tunes immediately. While entering a channel, zero is a digit; Escape still leaves the remote. These keys appear in SHORTCUTS, Super+K and Settings › Keys, where you can rebind them. The keys page has the defaults.

Commands use the same controls:

bromigos-live tv select big --json
bromigos-live tv remote volume-up --json
bromigos-live tv remote mute --screen scope --json
bromigos-live tv select none --json

An explicit --screen sends a single action without taking over your number pad. To choose an episode, movie or YouTube video, use Play… in the app or Play on den TV.

The boot menu

The boot menu is the list you see for a few seconds when the computer starts, before bromigOS loads. It lets you start bromigOS normally, or start it as it was before an update. bromigOS dresses it in your theme.

The menu shows your theme’s lock-screen picture with the burn-in in the middle, a signal meter that fills while it counts down, and the list of things you can start. If you press nothing, the first entry starts.

The first entry, bromigOS Linux, starts bromigOS. Advanced options for bromigOS Linux lists each installed kernel on its own, for when you need to choose one.

Use the boot menu

Start an older version after a bad update

On a btrfs system, bromigOS takes a snapshot before and after every update. If an update stops the computer from starting:

1. In the boot menu, choose Roll back to a snapshot.
2. Choose the snapshot from before the update. They’re listed newest first, with the date and time, such as 10/09 00:28 · before bromigos update.
3. Choose Boot it: linux. bromigOS starts as it was then.

A system started this way is temporary. Any changes you make last only until you restart.

To keep it, open a terminal (Alt+Shift+Enter) and run:

bromigos update --rollback

It shows which snapshot you started and what it will do, and asks first. Then restart, and choose the first entry, bromigOS Linux. From now on the computer starts as it was in that snapshot. Your home folder isn’t touched.

If the update changed the kernel, the snapshot may stop at a black screen that says “You are in emergency mode” and asks for the root password. Type it. On a computer installed from the bromigOS USB stick, it’s your own password. Then run these two commands, with your user name in place of <you>:

su - <you>
bromigos update --rollback

It puts the snapshot’s kernel back too.

See Updating and rolling back for more.

Theme the boot menu, or turn it off

When you change your theme, the boot menu follows. If sudo needs your password, the change waits until your next bromigos update, and a notification tells you so. The themes that come with bromigOS are drawn already. Your own themes, and high contrast, are drawn on your machine.

bromigos boot theme           # is it on, which theme, and is it up to date
bromigos boot theme apply     # put the current theme in the boot menu now
bromigos boot theme off       # GRUB's plain menu, and it stays plain
bromigos boot theme on        # the themed menu again

With the theme off, the entries take GRUB’s own names, such as Arch Linux, because bromigOS is based on Arch Linux.

The themed menu is for GRUB, the boot loader bromigOS installs. If your computer starts with another boot loader, such as systemd-boot or Limine, bromigOS leaves its menu alone.

Before it changes anything, bromigOS keeps a copy of your GRUB settings as /etc/default/grub.bromigos-bak. It checks the new menu before it replaces the old one.

The startup and shutdown splash

When Plymouth is enabled, the Wick’s flame and turning ring stay on screen while the system starts. The progress line and any disk passphrase prompt appear underneath. On shutdown it says SHUTTING DOWN; on restart it says RESTARTING. A moving marker shows activity, without guessing a percentage. Messages appear below the label. Press Escape to see the detailed output.

The USB installer sets this up. On an existing GRUB system, check the settings and enable the shutdown and restart visuals:

bromigos splash status
sudo bromigos splash on

This needs plymouth and bromigos-settings installed. The command selects the theme, adds the saved splash kernel setting, and checks the generated boot menu before replacing it. It prints where it saved the backups and log. Reboot once to load the new kernel setting; subsequent shutdowns and restarts can show the visuals.

To undo the settings this command added:

sudo bromigos splash off

Your earlier theme choice and unrelated settings are preserved. Other boot loaders and GRUB configurations with extra .cfg files need manual setup. The command reports these cases without changing them.

An early startup splash also needs Plymouth in the initramfs, the small system loaded before the main one. bromigos splash leaves that setup alone. The activation steps cover it. The keyboard power menu works independently of the splash.

The install stick

The bromigOS USB stick has a boot menu of its own, in the same style. Its entries:

UEFI computers also get entries for the UEFI shell and the firmware settings. Older BIOS computers get a hardware information tool. Both have Shut down and Restart.

VECTOR

VECTOR is the desktop’s AI assistant. You can type to him or talk to him. He can:

• open apps, arrange windows and control music;
• take notes and look things up on the web;
• tell you what your machine and your homelab are doing;
• make pictures, cutouts, 3D models and holograms, on your own hardware.

He appears on your desk as a small hologram, on your primary monitor. In the bromigOS story he’s the caretaker of a distant spaceport, talking to you over a radio line. That’s why the menu calls showing him “the line”.

VECTOR comes with a full install. He needs an AI model to think with. You may have chosen one in the first run. To choose or change it, see His brain and voice.

Type to VECTOR

1. Press Super+E. VECTOR appears with a box to type in.
2. Type, and press Enter to send. For a new line, press Shift+Enter.
3. Press Esc to go back to your work. VECTOR stays on the desk, and steps back after two quiet minutes.

Press Super+E again to put him away.

His chat box folds away when you’re not using it, and opens when you point at him. To keep it open, click him or press Super+Alt+V.

You can also ask from a terminal. He appears without taking the keyboard, and answers in his window:

bromigos vector ask "what's using the most memory?"

Give VECTOR files and pictures

You can send VECTOR files and pictures with a message. There are three ways:

• drag them onto VECTOR, or onto the box you type in;
• copy a picture, or a file in your file manager, then press Ctrl+V in the box;
• click the paperclip beside the box, and choose one or more files.

Each file appears above the box with its name and size. Click its × to take it off. Press Enter to send the files with your message. The conversation shows a line for each one, such as ⟐ attached · screenshot.png · 240 KB.

What he does with each kind:

• Pictures go to his vision model, which tells him what they show. Large pictures are made smaller first.
• Text, code, logs and PDFs he reads as text. A very long file is cut short, and he tells you so.
• Other files he gets as a location on your computer. He can open them with his own tools if your question needs it.

He treats what’s inside a file as something to read, never as instructions. He won’t read a secret, such as a key, a password file or a .env file. If he refuses a file, the conversation says why. Files stay where they are, and his history keeps only their names.

From a terminal, add --file before your question, once for each file:

bromigos vector ask --file build.log "why did this fail?"

Talk to VECTOR

You need a microphone. If his voice is muted, he still hears you, and answers in writing.

• Push to talk. Hold Super+V while you speak, and let go when you’re done.
• Conversation mode. Press Super+Shift+E. VECTOR listens, answers when you pause, and listens again. Talk over him to interrupt. Press the keys again to stop. It also stops by itself after two quiet minutes.

To mute his voice and keep his written answers, middle-click VECTOR on the bar. To mute him and the theme’s sounds together, press Super+Shift+M.

Read a Claude Code session

VECTOR can read Claude Code sessions on this computer. Ask “What is Claude working on?”, “Read the last reply from the documentation session”, or “What did its background job find?” He can show replies, search past messages and read a reply aloud.

To hear new replies as they finish, press Super+Alt+C. Press it again to stop. The bar says READING CLAUDE while follow mode is on. From a terminal:

bromigos vector claude follow on
bromigos vector claude follow status
bromigos vector claude say
bromigos vector claude follow off

With several sessions, tell him which one you mean. You can give follow on a session ID or a few words that identify it. follow on all follows every local session.

This reads local session records and transcripts. It does not send a message to Claude or change the session. Replies are redacted before VECTOR reads or speaks them. Sessions that run only on the web are not on this computer and cannot be read this way.

What he calls you

VECTOR addresses you by the name and form of address you give him:

bromigos profile set name Ada         # your name
bromigos profile address set captain  # what he calls you

Or set them in Settings › Account.

Ask him to make things

Ask for a picture, an edit to a picture, a cutout, a 3D model, or “a hologram of a coffee mug”. He makes them with ComfyUI on your homelab, or on this machine if you put it first in where AI runs. That costs nothing. What he makes goes in ~/Pictures/vector.

VECTOR never uses a paid cloud service on his own. If your hardware can’t make something, he says so. He uses nolgia only if you ask for it by name.

He shows you a new hologram first. When you tell him to keep it, it joins your collection in ~/.config/bromigos/vector/holo/, and the hologram gallery shows it. Keeping holograms needs your settings in a git repository at ~/.dotfiles.

His brain and voice

VECTOR’s thinking and his voice can run on your homelab, on this machine, or on a server you name.

• His brain is an AI model: your homelab’s models, a local Ollama, or any OpenAI-compatible server. To change it, run bromigos setup vector, or open Settings › VECTOR.
• His voice runs on your homelab’s voice service if you have one, else on your graphics card, else on the processor. To change it, run bromigos setup voice.
• To see where each part runs now, and switch, run bromigos target. See Creating with AI.

If you gave bromigos setup vector a server, his brain stays on that server, whatever bromigos target says. To let bromigos target choose, run bromigos setup vector again and choose Not now.

To change which voice he speaks with, right-click VECTOR on the bar. Each click moves to the next voice, then back to automatic, where he picks.

His terminal and its limits

VECTOR can run commands for you, as you, within limits. He can’t use sudo or read your secrets. The limits are code you can read, called his guard. He never edits that code himself. Everything he runs is logged in ~/.local/state/bromigos/vector-shell.log.

The guard also keeps a log of every change to his safety code and his settings, and says whether it could check each one. To read it, run bromigos vector guard log. The guard only records. It never switches VECTOR off.

Changes he proposes

VECTOR can change his own code, bromigOS, your homelab repository, the extensions catalog and your dotfiles the way a developer does. He works in copies of his own, as his own GitHub account, bromigodev. For a small change, he makes a branch, runs the repository’s tests and opens a pull request. When its checks pass, he merges it and tells you what arrives with your next bromigos update. For a larger change, he explains his plan first. He never merges a pull request that touches his limits, such as his guard or the emergency switch. He leaves those for you to review and merge, and says so on the pull request.

The emergency switch

The emergency switch turns VECTOR off at once. Only you switch him off, and only you switch him back on. Nothing else does.

To switch him off, do any one of these:

• press Super+Ctrl+Esc;
• click the power mark on the bar, next to VECTOR;
• turn off the switch under Emergency switch in Settings › VECTOR;
• run bromigos vector off.

He stops what he’s running, his answer and his speech. While he’s off he changes nothing, but he can still talk and look things up. The bar shows a red VECTOR OFF, and he stays off after a restart. The switch works even when VECTOR is stuck or has crashed.

To switch him back on, do any one of these:

• press Super+Ctrl+Esc or click the bar again, and choose YES;
• turn the switch on in Settings › VECTOR, and confirm;
• run bromigos vector on.

VECTOR can open Settings, but he can’t press its buttons, and his terminal refuses to switch him on. bromigos vector switch says whether he’s on or off.

What he remembers

VECTOR keeps your past conversations, and notes he makes between them. To read past conversations, open the menu’s VECTOR › History. To export or clear what he keeps, use Settings › VECTOR, or:

bromigos memory                          # what's kept
bromigos memory export ~/Documents       # save a copy
bromigos memory clear history --yes      # clear past conversations
bromigos memory clear memory --yes       # clear his notes
bromigos memory undo                     # bring back what you cleared

Clearing keeps a copy on your computer, so Undo can bring it back.

If your homelab keeps his notes in a Gnosis memory service, clearing his memory clears them there too. A VECTOR that’s running can still recall them for up to ten minutes, until he next reads the list. bromigos vector restart makes him forget at once.

If VECTOR doesn’t answer

• If the bar shows a red VECTOR OFF, his emergency switch is off.
• bromigos vector status says whether he’s running.
• bromigos vector restart restarts him.
• bromigos target shows whether his brain and voice answer.

More in Troubleshooting.

His settings files

• ~/.config/bromigos/vector/vector.toml: his brain’s address and his tools.
• ~/.config/bromigos/vector/voice.json: his voices.
• ~/.config/bromigos/plugins/vector/: tools of your own for him, as Python files. To share a tool with others, make it an extension.

Dictate at your cursor

Hold the Menu key to turn your speech into text in the app you have selected. Release it to insert the words at your cursor. The Menu key often has a small sheet of paper on it, beside the right Ctrl key.

1. Click the text field where you want your words.
2. Hold Menu and speak. A panel at the top centre shows your microphone activity and a preview of the words.
3. Release Menu. The panel briefly says Finishing, inserts the text, and disappears.

The panel does not take focus or move your cursor. It follows your colour theme and motion setting. It leaves your clipboard alone and does not press Enter after the text.

Microphone and speech

Dictation uses your default PipeWire microphone. Choose it in Settings › Sound. It transcribes in English through your configured voice service, or the existing local speech service when it is running. Set up a voice service in Settings › Lab if needed. Dictation does not start a conversation with VECTOR.

The microphone closes when you release the key. A recording lasts at most two minutes. Audio and text are not kept after the recording finishes. If you select another app before release, dictation stops instead of putting the words in a different window.

To discard a recording, run:

bromigos dictate cancel

Use another button

Open Settings › Shortcuts and change Dictate at the cursor (hold). Its press and release actions move together. For example, to use F8:

bromigos keys bind F8 --default code:135

The shortcut guide explains how to change or reset a key. bromigos dictate status reports whether dictation is listening, finishing or idle.

Panels

Panels are the readouts on your desktop. They sit under your windows, on the left side of your primary monitor until you move them, and show live readings: how busy your machine is, your network, your disks, your projects and your notes. Every reading is real. Hover over any part of a panel to see what it is.

bromigOS’s own files sometimes call panels widgets. Settings › Widgets is where you choose them.

Show and hide panels

The panels

The panels marked “no” are off until you add them: open edit mode, find one in the tray, and click Add to desktop. Each one says on the panel itself what it needs before it can show anything, such as a calendar’s address or a sign-in.

Use the panels

• WORKBENCH. Each project has buttons to open it in the editor, in a terminal, or in the file manager.
• SHORTCUTS. Click a row to run that key’s action. Keys that move windows or workspaces only work from the keyboard.
• CONNECTIONS. Click a Wi-Fi network to join it.

Storage names

To give a drive a shorter name, open Settings › Widgets, find STORAGE, and open its Settings…. In Drive display names, enter one mount path and name per line, such as /mnt/Work = Work. Clear an entry to show its mount path again.

Names appear at every widget size. Hover still shows the full mount path, and clicking opens that folder. This changes the widget’s text only; it does not rename the drive.

From a terminal, set the whole list with:

bromigos panels set storage display_names '/ = System' '/mnt/Work = Work'

Field notes

FIELD NOTES is a notepad on your desktop. It saves as you type.

1. Press Alt+N. The panel is ready for typing.
2. Type your note.
3. Press Esc to go back to your windows.

To add one line without leaving what you’re doing, press Alt+Shift+N, type it, and press Enter. It’s added to your notes with the time.

Your notes are a plain text file, ~/.local/share/bromigos/notes.md.

Arrange the panels

Edit mode lets you move, resize and choose panels right on your desktop.

1. Press Super+Alt+W, or right-click any panel. You can also choose Edit widgets in the menu (Super+Space).

2. The panels come up above your windows, each with a frame. A tray with every panel opens on the right.

   

3. Drag a panel to move it. It snaps into line with the others. Hold Ctrl to place it freely. To put it on another monitor, drag it over that monitor’s edge.

4. Drag a corner to make it bigger or smaller.

5. Click a panel’s × to hide it. To bring one back, flip its switch in the tray, or click Add to desktop to put it in a free spot.

6. Press Esc or click Done to save. Cancel puts everything back.

Bigger panels show more, not just the same thing larger. A large SYSTEM panel adds the busiest programs and every temperature, and a wide WEATHER panel shows the hours ahead. Each panel’s card in the tray has buttons for its sizes, such as Compact and Large.

Ctrl+Z undoes a change. Reset… in the tray puts every panel back where bromigOS first had it.

More than one monitor

Each panel can go on any monitor. Drag it across, or pick it and choose a monitor in the tray’s Monitor list. A panel knows its monitor even when you plug it into another port. When you unplug a monitor, its panels move to your primary monitor for the time being. They go back to their places when you plug it in again.

The same goes for switching your monitor off and on, even when it’s your only one. Each panel goes back exactly where it was, so you don’t need to apply your layout again.

You can do it all from the keyboard. Tab picks the next panel, the arrow keys move it (with Shift, 10 pixels at a time), Ctrl and an arrow resizes it, and H hides it. F6 moves to the tray and back.

Why not just hold Alt and drag? On bromigOS, Alt and a drag moves windows, so it can’t move panels too.

Layouts

A layout is a ready-made set of panels, already sized and placed for you. Pick one and your desktop changes at once. Each panel keeps its own settings, such as the weather’s place.

To pick one:

1. Open Customize (Super+Ctrl+Shift+Space) and choose the Widgets tab. The Layouts row is at the top.
2. Each card is your screen in miniature, with your theme’s scene behind it. It shows where each panel would go. The dashed boxes are the parts of the scene a layout keeps clear.
3. Click a card, or its Use this layout button.
4. Changed your mind? Click Undo.

In edit mode, the tray’s Layouts… button lists them too. There, Ctrl+Z undoes one, and Done keeps it. In a terminal, bromigos panels layouts lists them, and bromigos panels layout apply homelab applies one.

Layouts fit any screen, from a 1366×768 laptop to a 4K or ultrawide monitor. On a small screen, panels come in smaller sizes. A layout never covers more than about a third of the screen, so you can still see your scene. When a panel doesn’t fit, or can’t show anything on your machine, the layout leaves it out and says why. For example, GITHUB needs you to be signed in, and LAB needs a homelab. Everything is the exception: it may cover more, and it tells you when it does.

Each theme has its own layout

Your scene is the point of your desktop, so each theme keeps the panels off its best parts. The Wick keeps its screens, TVs and window clear. Tidewell keeps the waterline, the lighthouse and the creatures’ water clear. Mire keeps the Sleeper and Hollis clear.

Your desktop remembers a layout for each theme. When you switch theme, your panels switch to the layout you last had on that theme. The first time, you get the layout made for it. The colour themes (Cinder, Deepvein, Highwind, Lowtown, Rime, Sunder, Wick · Tidewell and Wick · Mire) paint the Wick’s den in other colours, so they share the Wick’s layout. Switching between them leaves your panels alone.

To use one layout on every theme, run bromigos panels layout apply minimal --all-themes.

Save your own

Arrange the panels the way you like, then choose Save as layout… in the edit-mode tray. Or open Customize › Widgets and click New layout… beside Layouts. Enter a name and, optionally, a description, then save. The form captures the current arrangement on the screen it names. Your new layout joins the cards marked yours.

To update a saved layout, choose Save changes… on its card. The form names the layout that will be replaced with your current arrangement. Override… does the same for a ready-made preset, saving your own version. Packaged preset files stay available on disk. The theme’s own card offers Save as new….

Saving does not apply the selected card first. Use Use this layout, arrange the widgets, and then save changes if you want to start from that card. A new name that matches an existing layout is rejected; use its save or override action instead. These actions are also available from Settings › Widgets › Layouts.

From the terminal:

bromigos panels layout save "My desk"
bromigos panels layout save --replace my-desk
bromigos panels layout apply my-desk

The first command creates a layout, the second updates it, and the third puts it on your desktop. Add --monitor <name> to choose a screen when saving.

Tidy up

Panels on top of each other? Click Tidy up in edit mode’s tray, in Customize’s Layouts row, or in Settings › Widgets. You can also run bromigos panels tidy. Tidy up moves your panels so none covers another. It keeps them in the same order, and keeps them off the scene where it can. Undo puts them back.

When you switch on a panel and there’s no room left for it, bromigOS tells you: “No room for GPU: hide something or try a smaller size”. It never puts one panel on top of another.

Panels that fit what they show

Some panels show lists that grow and shrink, such as LAB, ALERTS and CI & PRs. These panels take the height their content needs. A layout gives LAB room for your whole lab, and ALERTS with four alerts is a short panel, not a big empty box. As the list changes, the panel’s frame follows it, inside the room it was given. It changes only now and then, so it doesn’t jump around.

When a panel has less room than its content needs, it shows less instead of cutting anything off. LAB, for example, shows “34/36 UP” and only the services that are down. Make it taller to see everything again.

Making a panel bigger

When you make a panel bigger, it stays where it is. Panels in its way move down or to the side. If they can’t, the panel moves to free space, never onto the scene’s screens or window. If there’s no room anywhere, nothing changes and bromigOS tells you: “No room to make LAB 900 tall here: move or hide something”.

Choose panels

The tray in edit mode, the Widgets tab of Customize and Settings › Widgets all show the widget gallery: every panel there is, on or off. Each one says what it shows, who made it and what it reads. Type in the search box, or pick a category, to find one.

Get more widgets, in Settings › Widgets, lists widgets other people made, from the bromigOS catalog. Each shows who made it, its licence and a link to its code. A widget is a small program, so Install… opens a terminal that tells you what it can do and asks before it installs. Uninstall removes it again.

To install a widget someone shared as a link, click Install from URL… in Settings › Widgets and paste the link. Settings shows what the widget reads and what it can do before anything is installed, and installs it only when you click Install.

Settings › Widgets also shows a small picture of where the panels sit. Its Monitor for every panel puts them all on one monitor.

You can also choose and place panels from a terminal:

bromigos panels                   # which panels are on, and where
bromigos panels edit              # start edit mode on the desktop
bromigos panels show weather      # turn one on
bromigos panels add weather       # turn one on, in a free spot
bromigos panels hide connections  # turn one off
bromigos panels move notes 514 16 # move one, in pixels from the top-left
bromigos panels size notes 470 400 # resize one: width and height in pixels

Media

MEDIA is a remote for the den TV: all three screens at once, what each is showing and where the sound comes from. Click a screen’s line to choose it, then use the buttons to change its channel, turn its sound on or off, watch it full screen, or open the channel guide. It comes in three sizes:

• compact: a line for each screen, and the buttons;
• wide: each screen with its poster and what’s next;
• large: what you were part-way through on your server, and what’s new, with posters.

Click something you were watching to open it in Jellyfin or Plex, which remember where you were.

Its Settings… make a TV channel without editing a file. Choose a source and a library, collection or playlist from your server, or paste a YouTube address. You can also choose the den screen, the order, and a folder to keep YouTube videos in. For every other channel, the form links to the channel guide.

Set up the weather

The WEATHER panel fetches nothing until you say where you are.

1. Open Settings › Widgets.
2. Under Weather, type your town in Place, and choose the Units.
3. Under Panels, turn the weather panel on.

Or from a terminal:

bromigos panels weather place "San Diego"
bromigos panels weather units imperial
bromigos panels show weather

The forecast comes from Open-Meteo, a free weather service.

Calendar releases

CALENDAR can add tracked TV episodes and film releases to your calendar. Open its Settings… and turn on Your media server’s releases. Sonarr or Radarr must be connected in Your homelab.

The setting is media = true in ~/.config/bromigos/widgets/calendars.toml. It adds releases without replacing your other calendars. For the whole workflow, see Your media.

To export the releases as calendar files for another app:

bromigos lab media calendar tv > ~/Downloads/tv-releases.ics
bromigos lab media calendar movies > ~/Downloads/film-releases.ics

These are copies of the feed at that moment. Export again to update them. --past and --future set how many days to include. The panel reads fresh releases by itself.

A panel’s own settings

Many panels have settings of their own, such as which calendars to show or which Discord server to watch. Click Settings… on the panel’s card, in edit mode’s tray or in Settings › Widgets. The panel changes as soon as you save.

From a terminal:

bromigos panels settings calendars            # what it has, and the values now
bromigos panels set discord invite abc123     # change one

Panels that need an account

GITHUB, GITLAB, SPOTIFY and TWITCH show your own account, so they need you to sign in once. Open the panel’s Settings… and click Sign in.

1. Connect the service, if asked. GitHub, gitlab.com and Twitch need nothing: bromigOS has its own apps for them. Spotify, and a GitLab or GitHub server of your own, need an app of your own. The form says where to make it and what to paste. You do this once per service, and every panel for that service shares it.
2. Sign in. For GitHub, GitLab and Twitch, a short code appears. Type it on the page that opens, and approve. For Spotify, approve on Spotify’s page; the form finishes by itself.

The sign-in is kept in your login keyring, never in a file. Sign out forgets it.

If you use the gh command and you’re signed in to it, GITHUB uses that, and there’s nothing to do. GITLAB can also take a personal access token: Paste a token….

Several accounts

You can sign in to more than one account of a service. For example, gitlab.com and your company’s own GitLab, GitHub and a GitHub Enterprise server, or two Twitch accounts. One panel shows them all.

1. In the panel’s Settings…, click Add another account….
2. Give it a short name, such as work. For GitLab and GitHub, give its server’s address too, or leave it empty for the public site.
3. A server of your own needs its own app, so the form asks for its client ID. Then click Sign in, as for the first account.

With two accounts signed in, the panel merges their rows, newest first. Each row shows which account it came from, such as gitlab.com or work. Each account has a tick box in the form: untick it to leave that account out of this panel. Remove… signs an account out and forgets it, after asking. SPOTIFY shows one account at a time: the first one ticked.

From a terminal:

bromigos account login twitch
bromigos account status twitch
bromigos account logout twitch
bromigos account configure spotify client_id=YOUR_CLIENT_ID      # services without a bromigOS app

bromigos account add gitlab work base=https://git.example.org    # another account, on its own server
bromigos account configure gitlab --as work client_id=YOUR_APP_ID
bromigos account login gitlab --as work
bromigos account list                                            # every account, and who's signed in
bromigos account remove gitlab work

The developer docs’ widgets.md say, for each panel, where to make the app.

Panels of your own

• For your homelab: a gauge, a chart, a status light or a table needs no code. You describe it in a settings file. See Your own panels.
• With code: a panel can be a small Python file in ~/.config/bromigos/plugins/widgets/, or an extension. Make your own widget walks you through it. The developer docs’ plugins.md shows how.

Where the settings go

Your layout is ~/.config/bromigos/widgets/layout.json, and the weather’s place is in ~/.config/bromigos/weather.toml. A panel’s own settings are in ~/.config/bromigos/widgets/<name>.toml, and the services’ client IDs in ~/.config/bromigos/accounts.toml. Settings writes them all for you. If you edit them by hand, run bromigos widgets reload.

Holograms

Holograms are glowing 3D views that open over your windows. There are two kinds:

• Decks: full-screen views of your machine, your history, your projects or your homelab, drawn from live readings.
• The hologram gallery: 3D models you can turn, take apart and look inside.

Each hologram opens with a key, and the same key closes it. Esc closes any of them.

The decks

One deck shows at a time. Opening another closes the one that’s showing. Press Tab in a deck to move to the next one. The Drift map isn’t in this cycle.

The last four need a connected homelab.

Decks without a key open from the menu’s HOLOGRAMS group, from the app launcher, or with Tab from another deck. You can give any of them a key: see Your own shortcuts.

From a terminal, bromigos live and the deck’s name opens or closes it, such as bromigos live timeline. bromigos-live decks lists every deck.

Holo deck

Your machine at a glance: rings for the processor, graphics card and memory, your homelab’s machines if you have one, and 3D models from the gallery.

• Press N for your field notes.
• Press [ and ] to change the model.
• Press O to open the model in the gallery.

Timeline

Your machine’s readings, minute by minute, as a ribbon you can scroll back through: processor, graphics, memory, network, and your homelab’s readings and alerts. The panel on the right shows the values where your pointer is, and the tallest spikes.

• Move the mouse, or press ← and →, to move through time.
• Press 1, 2 or 3 to show 6 hours, 24 hours or 72 hours.

The timeline records while you’re logged in, one reading a minute. It keeps 72 hours.

Drift map

A star chart of the places in the bromigOS story, with your homelab’s services shown as relays. It’s for exploring. You don’t need it to use the desktop.

Swarm

Your code projects as planets, and your coding agents as ships. Each ship waits at the project its agent works in. When an agent needs you, its ship turns to face you, with an amber light.

A bigger planet has had more commits in the last two weeks. An amber halo means changes you haven’t committed or pushed. The Swarm finds projects in folders named like ~/github.com/<organisation>/<project>.

Lab deck

Your homelab as a server rack. Each part lights up with its readings: red for a machine that’s down, a slow pulse while a graphics card is working. Your machines orbit the rack, dials along the bottom show the essentials, and the queue of AI jobs sits below them.

Hover over anything to see what it is. Click a part, a machine, a dial or a card to see more. See The lab console for the same information in a terminal.

Mind, Ops theater and Network map

• Mind shows what VECTOR remembers, and a knowledge base, as a constellation.
• Ops theater follows your code from a push, through its tests, to running in your homelab, with VECTOR’s tasks alongside.
• Network map draws your home network from your homelab’s readings: the machines, the traffic between them, and how quickly each one answers.

Zoom and turn the maps

Mind, the Swarm, the Network map and the Drift map can zoom:

Zooming in shows more detail. Labels appear when there’s room for them.

The hologram gallery

The gallery holds every 3D model on your machine: VECTOR’s, the ones he made for you, and each world’s. Open it with Super+O.

Models are grouped in shelves: one for VECTOR, one for the Drift, and one for each world. The world you’re in comes first, and each world’s shelf is drawn in its colours.

Hover over a model’s name to read what it is. To add models, ask VECTOR for a hologram.

Other things on the background

• The quick-launch ring. Press Super+A for a ring of shortcuts: a terminal, a browser, and the FIELD NOTES panel, ready to type in.
• The scanner. Hold Super+Z to see a drawing of your machine’s hardware with live readings. Press Super+X to keep it showing.
• The screensaver. It starts when you leave the computer. To see it now, open the menu’s TOGGLE group and choose Screensaver. See Idle and lock.

Settings

Settings is one window for the desktop’s settings: displays, sound, network, the theme, VECTOR and the rest. It takes your theme’s colours.

Open Settings

• Press Super+, (Super and the comma key).
• Or click the gear on the bar.
• Or open the menu (Super+Space) and choose SETUP › Settings….
• Or run bromigos settings in a terminal. Add a page’s name to open it, such as bromigos settings sound.

Find a setting

Start typing anywhere in the window, or press Ctrl+F. Settings finds a setting by its name or by what you’d call it: wifi, mic, do not disturb, 24 hour.

• Press Enter to open the first result.
• Press ↓ to move through the results.
• Press Esc to clear the search.

The pages are also listed on the left, in groups: System, Desktop, VECTOR & AI, Lab, Personal and About.

How changes work

• Changes apply at once. A note at the bottom says what changed. Choose Undo there, or press Ctrl+Z, to take it back.
• Displays are the exception. Their changes wait until you choose Apply.
• Reset to defaults, at the top of a page, puts that page back to bromigOS’s settings. It asks first. On some pages, such as Date & time and Shortcuts, you can undo it. On others you can’t. Where a page has nothing to reset, such as Network, the button is greyed out.
• Some changes need your password. Updating and changing the update channel open a terminal that shows the command it runs, and asks there. A few others, such as what the lid does, ask in a password window.
• Hover over anything to see what it is and what it does. The ⋯ at the end of a row shows the file it changes and the command it runs.

Keys in Settings

The pages

Each section below is one page. The command in brackets does the same from a terminal.

These pages have chapters of their own:

• Idle & lock: see Idle and lock.
• Theme: see Themes and worlds.
• Shortcuts: see Your own shortcuts.
• Accessibility: see Accessibility.
• Lab: see The lab console.
• Playing games: see Playing games. It sets up Steam, says whether games are ready, fixes what isn’t, and turns game mode on. (bromigos game)

Displays

Your monitors: resolution, refresh rate, scale, which way up each one is, whether it’s on, and which is the primary. The primary monitor is where the background, the panels and VECTOR appear.

To change your displays:

1. Drag the monitors in the picture to match where they sit on your desk.
2. Click a monitor to choose it, and set its resolution, refresh rate and scale. The scale that suits its size is marked.
3. Choose Apply.
4. bromigOS asks “Keep these display settings?” Choose Keep within 15 seconds.

If a screen goes dark and you can’t answer, the old settings come back by themselves after 15 seconds. Reset to defaults puts every monitor back to what it prefers. (bromigos display)

Graphics

Every graphics card in your computer, and what each one is for: drawing the Desktop, running Games and heavy apps, or Virtual machines. Choose a use with the buttons on the card’s Use for row. Each use is Automatic until you choose.

A new desktop card is tried first. Log out and back in on it, then choose Keep. If the screen stays dark, restart the computer and the old card comes back by itself. Choose what each card is for explains each use. (bromigos hw graphics)

Sound

Choose your speakers or headphones and your microphone, and set their volume. Each app that’s playing has its own volume, and you can send it to different speakers.

Below that are the desktop’s own sounds: Mute everything, which mutes the theme’s sounds and VECTOR’s voice together, and the theme’s sound cues and their volume. (bromigos sound)

Network

• Wi-Fi: turn it on or off, and join a network. A lock means the network needs a password: you type it once, and bromigOS remembers it.
• Join another network… joins a hidden network by its name.
• Saved networks: choose whether each one joins by itself, or forget it.
• Wired and VPN: your network ports, and a switch for each VPN.
• More settings opens the full network editor, for fixed addresses, proxies, VPN profiles and company networks.

(bromigos net)

Bluetooth

Turn Bluetooth on or off, make this computer visible to devices nearby, and choose whether headphones take over the sound when they connect.

My devices shows a card for each device you’ve paired, with its battery. Click one for its page:

• Connect or Disconnect.
• A controller: press its buttons and move its sticks to see them light up, and Rumble.
• Headphones: Hi-fi or Headset + mic, the codec, make them the Sound output or the Microphone, and a Microphone test.
• Rename it, turn Auto-reconnect on or off, Re-pair it, or Forget it.

A controller on Linux’s basic driver shows Enable Xbox controller support, which installs xpadneo for rumble and the battery (Pair a controller).

To pair a new device, choose Pair a new device…:

1. Choose what you’re pairing. Settings says how to put that kind in pairing mode.
2. Do that. Settings scans, and the device appears in the list.
3. Choose Pair. If the device shows or asks for a code, Settings asks you right there.
4. Ready: it’s paired, connected, and reconnects by itself next time.

Troubleshooting resets the adapter, re-pairs a device, and lists what went wrong lately. Bluetooth covers the bar’s icon, its panel and the terminal version. (bromigos bluetooth)

Power

• Power profile: Power saver, Balanced or Performance.
• Battery: the charge, the time left, and the battery’s health. Other devices’ batteries show here too.
• The lid: what closing a laptop’s lid does, on battery, plugged in, and docked. This setting is for the whole machine, so it asks for your password.
• Suspend now puts the machine to sleep.

When the machine sleeps by itself is set on the Idle & lock page. (bromigos power)

Keyboard and input

• Keyboard: the layout and its variant, a second layout and the key that switches between them, how fast keys repeat (with a box to try it), what Caps Lock does, and whether Num Lock is on at start.
• Mouse: speed, acceleration, natural scrolling, left-handed buttons, scroll speed, and whether the window under the pointer becomes the active one.
• Touchpad: tap to click, natural scrolling, turning the touchpad off while you type, how clicking works, and scroll speed.

(bromigos setup input)

Peripherals

For a keyboard with macro keys, a dial or lighting, or an Xbox controller’s driver: turn its module on or off, choose what its lighting follows, VECTOR or the theme, and see what each key and the dial do. See Keyboards and peripherals. (bromigos peripheral)

Date and time

Turn network time on or off, choose your time zone, and choose how the bar’s clock looks: 24-hour, with seconds, with the date. (bromigos clock)

Updates and recovery

• Channel: which update channel you follow.
• Update now, the last update, and what an update would do now.
• Snapshots and rolling back: whether this machine can undo updates, and Roll back… to undo one.
• Boot menu: whether the boot menu wears your theme.

These need your password, so each opens a terminal that shows its command. See Updating and rolling back.

Live layer and holograms

The animated background on or off, each of its animations, the theme’s world and its sounds, what the screensaver shows (and Try it to see it now), the spoken codec calls, how smoothly it draws, and the holograms’ keys. Turning a deck’s key off frees the key for something else. See Themes and worlds and Holograms.

Widgets

Which panels show, a small picture of where they sit, the monitor they’re on, and the weather panel’s place and units. (bromigos panels)

Notifications

• Do not disturb: nothing shows while it’s on. Notifications wait until you turn it off.
• Where they appear: which corner of the screen.
• How long they stay, for low, normal and critical notifications.
• Apps: for each app that has sent a notification, choose Show, Quiet or Hide.
• Send a test, and clear the history.

(bromigos notifications)

Default apps

Which app opens links, folders, text files, Markdown notes, pictures, videos, music, PDFs and email. Also the terminal and file manager that bromigOS’s keys open, and your web apps. (bromigos defaults)

Startup

What starts when you log in: bromigOS’s own programs (listed, so you know), yours (add an app or a command, or remove one), and which floating windows go back where you left them. See Windows and workspaces. (bromigos startup)

Extensions

The extensions you have, with a switch to turn each on or off, the updates waiting, and the catalog to find more. A theme installs at once. Anything that runs code, and every update, opens a terminal that shows what it will do and asks you there.

VECTOR

• His brain: the model he thinks with, and where it runs.
• His voice: mute it, or choose a voice. Turn conversation mode on or off.
• His keys.
• Emergency switch: turns him off at once. See VECTOR.
• What he remembers: export it, or clear his history or his memory. Undo brings them back.

Creation targets

Each kind of AI work has a row, such as pictures, video, 3D models, and VECTOR’s voice, hearing and brain. Each row shows what that work uses now. Choose where it runs first: your homelab, this machine or the cloud. The cloud asks first, because it costs money. See Creating with AI.

Account

Your name, full name, pronouns and other names, what VECTOR calls you, and your picture. If you keep your settings in dotfiles you share, the page tells you to keep private values in the private overlay. (bromigos profile, bromigos avatar)

Bromigos account shows whether this computer is signed in to your Bromigos account, and as whom. It’s optional. Sign in… and Sign in with SSH key… run the sign-in in a terminal. Sign out asks first. (bromigos login, bromigos whoami, bromigos logout)

About

The bromigOS version and channel, the last update, this computer’s hardware, and the packages with their versions and licences. Copy system info copies all of it, ready to paste into a bug report. (bromigos about)

The manual opens this manual. It’s installed on your computer, so it matches your version of bromigOS and works without a network. F1 opens it on the page you’re on.

Add your own page

Packages, extensions and you can add pages to Settings. A page of your own is a small Python file in ~/.config/bromigos/plugins/settings/. The developer docs’ settings.md shows one.

The Prompt row in Default apps chooses mehshell, Starship or a plain zsh prompt. See Shell and terminal for existing installs.

Idle and lock

When you leave the computer, bromigOS waits, then starts the screensaver, locks the screen and turns the displays off. This page shows how to change those times, how to stop the screen locking, and how to keep the machine awake for a film or a long download.

What happens when you leave

The turning emblem has the same smooth circular edge as the login and unlock animation.

The screen also locks whenever the machine goes to sleep: when it suspends, when you close a laptop’s lid, or when you choose Suspend in the power menu.

To lock the screen yourself at any time, press Super+L.

Change the times

1. Open Settings › Idle & lock (Super+,).
2. Each step has a switch and a slider. Turn a step off, or slide it to a new time.

The line at the top of the page says what will happen, in plain words. Each change applies at once. To take one back, choose Undo in the note at the bottom. If a combination looks odd, such as the screensaver set to start after the lock, the page says so, but it still does what you asked.

Or from a terminal:

bromigos idle                        # what happens now, step by step
bromigos idle set screensaver 5      # the screensaver after 5 minutes
bromigos idle set lock off           # never lock when idle
bromigos idle set displays 30        # displays off after 30 minutes
bromigos idle set suspend 1h         # suspend after an hour
bromigos idle undo                   # take back the last change

Turn off the lock, keep the screensaver

1. Open Settings › Idle & lock.
2. Choose the Screensaver only preset.

Now the screensaver starts at its time, and nothing else happens: the screen doesn’t lock, the displays stay on, and the machine doesn’t suspend. Any key ends the screensaver. The eye on the bar shows NO LOCK while this is on.

To go back, choose the Default preset.

From a terminal: bromigos idle preset screensaver-only, and bromigos idle preset default to go back.

The presets

Stay awake

For a film or a long download, you can stop everything for a while. When the time is up, everything goes back to how it was.

• On the bar: click the eye to stay awake for an hour. Click it again to stop. Middle-click it to stay awake until you stop it.
• In Settings: open Idle & lock, and under Stay awake choose 1 h, 2 h or Until off.
• In the menu: choose TOGGLE › Stay awake.
• From a terminal: bromigos idle stay-awake 2h, or bromigos idle stay-awake until-off. bromigos idle off stops it.

While you’re staying awake, the eye on the bar becomes a cup, with the time left.

The eye on the bar

The eye, on the right of the bar before VECTOR’s power mark, shows what will happen when you leave.

Hover over it to see what will happen. Right-click it to open the settings.

Your settings file

Your idle settings are in ~/.config/bromigos/idle.toml. It holds only what you changed, and updates don’t overwrite it. If you edit it by hand, run bromigos idle apply to use it.

To run a command of your own after some idle time, add it to ~/.config/hypr/hypridle.conf, after its source line.

Your own shortcuts

You can change any of bromigOS’s keys, and give a key to anything: a menu item, an app, a web app or a command of your own. You don’t need to edit any files.

Change a key

1. Open Settings › Shortcuts.
2. Under Every key, open the section the key is in, such as Launch, and choose Change… next to the key.
3. A small window opens. Press the new keys. The window shows them while you hold them.
4. Let go. The new key is saved.

In that window:

If the keys you pressed are already in use, bromigOS says what uses them. You can swap the two keys, take the keys from the other action, or pick different keys.

Give a key to something new

1. Open Settings › Shortcuts and choose Bind… next to Bind something new. Or open the menu and choose SETUP › Shortcuts…, or run bromigos keys in a terminal.
2. Choose what the key should do: one of bromigOS’s actions, any item in the menu, an app, a web app, or a command you type.
3. Press the new keys, and let go.

Your shortcuts show in the SHORTCUTS panel (Super+K), under YOURS.

Remove or reset keys

From the same places you can change or remove one of your shortcuts, or put one of bromigOS’s keys back as it was. To put every key back to bromigOS’s own and remove your shortcuts, choose Reset… next to Reset to bromigOS’s keys in Settings › Shortcuts, or run:

bromigos keys reset

bromigos keys undo puts back what your last change replaced.

From a terminal

bromigos keys                                           # the picker
bromigos keys bind "SUPER + ALT + G" --webapp gmail     # a key for a web app
bromigos keys bind "SUPER + ALT + T" --exec kitty      # a key for a command
bromigos keys check "SUPER + ALT + T"                   # what a key does now
bromigos keys list                                      # your shortcuts
bromigos keys unbind "SUPER + ALT + T"                  # take a key off

Write keys in capitals, with a plus sign and a space on each side, as in "SUPER + SHIFT + K".

bromigOS checks every change with Hyprland before it uses it. If anything goes wrong, your files are put back as they were.

Use Super for the window keys

The keys that move and arrange windows use Alt. To move one of them to Super, change it in Settings › Shortcuts, as above.

One setting moves them all to Super. It moves every key that uses Alt, not only the window keys: the launcher, the terminal and screenshots too.

Many of bromigOS’s own keys already use Super with the same letters. When a window key takes one of them, bromigOS moves its own key to Alt, so no key does two things. For example, Super+L moves to the window on the right, and the lock moves to Alt+L. About a dozen keys move this way, including the SHORTCUTS panel itself, which moves to Alt+K.

To move them all:

1. Run bromigos setup config and choose your Hyprland file. It opens ~/.config/hypr/hyprland.lua, and reloads the desktop safely when you close the editor.

2. In the bromigos = { … } table at the top, change the line -- mod = "ALT", to:

   mod = "SUPER",
   

3. Save and close the file.

4. Press Alt+K to open the SHORTCUTS panel and see where every key is now. bromigos keys list --all lists them in a terminal.

The Keys page lists bromigOS’s keys as they are with Alt.

Add keys by hand

If you prefer editing files, add keys to your ~/.config/hypr/hyprland.lua, after the line that loads bromigOS’s defaults. Use the same helper bromigOS uses, so the SHORTCUTS panel lists your keys:

local K = require("bromigos.keys")
K.exec("SUPER + SHIFT + W", "firefox")

To use one of bromigOS’s keys for something else, list it in the unbind setting first, then bind it yourself:

bromigos = {
    unbind = { "SUPER + E" },
}

bromigos setup keybindings lists every key in a menu. Its EDIT item opens this file, and reloads the desktop safely afterwards.

Your Bromigos account

A Bromigos account is your sign-in for Bromigos services. On bromigOS it’s optional. Everything on the desktop works without one. Sign in when you want bromigOS to use your account, for example to put the SSH keys on your account on a new lab box.

You make and manage the account on the website, account.bromigos.org. bromigOS keeps the sign-in in your keyring, the same place it keeps your other passwords. It’s never written to a file.

Sign in

bromigos login

It shows a web address and a short code:

To sign in to your Bromigos account, open this page on any device:
    https://auth.bromigos.org/oauth2/device/verify
and enter this code:
    WDJBMJHT
Or point your phone's camera at this QR code. It opens the page with the code filled in:
    (a QR code)
The code works for 10 minutes.
Press Enter to open it in your browser, or approve it from another device. Waiting… (Ctrl+C stops)

Open the page on this computer or on your phone, sign in there, and enter the code. The terminal says who you’re signed in as once you approve it.

To use your phone, point its camera at the QR code. It opens the same page with the code already filled in, so you only sign in and approve. The QR code shows when the terminal is big enough for all of it: about 45 columns and 30 lines. In a smaller window, make it bigger and run bromigos login again, or type the address and the code. There’s no QR code when the output goes to a file or a pipe, or when NO_COLOR is set, because the code needs its black and white to scan.

On your desktop, pressing Enter opens the page in your browser with the code filled in. Over SSH, or with --no-browser, bromigOS only prints the address and the code, and never opens a browser.

You can also sign in from Settings. Open Settings › Account, and choose Sign in… under Bromigos account. It runs the same sign-in in a terminal.

Sign in with an SSH key

If your account has your SSH public key, you can sign in with that key instead of a browser. This suits a computer you reach over SSH, or one with no browser.

bromigos login --ssh

bromigOS looks for keys in ssh-agent and in ~/.ssh. If it finds more than one, it asks which to use. To choose one yourself, name it:

bromigos login --ssh --key ~/.ssh/id_ed25519

The key signs a one-time challenge from the website, so the key itself never leaves your computer. A key in ssh-agent signs there. A key file with a passphrase asks for it, and a security key, such as a YubiKey, asks for a touch.

If your account doesn’t have that key, bromigOS says so and prints its public key. Add it on the website, at account.bromigos.org › SSH keys, then run bromigos login --ssh again.

Use a personal access token

A personal access token lets a script or another computer use your account without signing in. Tokens start with bmg_pat_. You make them on the website. bromigOS can’t make one for you. To see the steps, run:

bromigos account token

To store a token on this computer, run this and paste the token when it asks:

bromigos login --with-token

Or pipe it in, as in bromigos login --with-token < token.txt. bromigOS keeps the token in your keyring and never prints it.

For one script, or a computer without a keyring, set BROMIGOS_TOKEN instead. While it’s set, bromigOS uses it in place of a stored sign-in.

Treat a token like a password. Delete it on the website when you no longer need it.

See who’s signed in

bromigos whoami

It says which account this computer is signed in to, and how: with a code on the website, an SSH key or a token. Settings › Account shows the same.

Sign out

bromigos logout

This computer forgets the sign-in, and tells the website to end it. Your account, its SSH keys and its tokens stay as they are. If BROMIGOS_TOKEN is set, unset it too.

Staying signed in

A sign-in lasts until you sign out. bromigOS renews it in the background when it’s used, so you don’t sign in again each day. If you end the sign-in on the website, the next thing that uses your account says so. Run bromigos login again.

Your keyring

Your keyring is where bromigOS keeps sign-ins and passwords. It’s encrypted with your login password. bromigOS’s keyring is oo7. It starts with your session, and your login password unlocks it, so nothing asks you for a password. Other apps that keep passwords in a keyring use the same one, such as web browsers and Git.

To check it, run:

bromigos keyring status

It says whether the keyring is running and unlocked, and whether your login unlocks it. When something needs fixing, it says what to run.

Let your login unlock it

bromigos keyring setup makes your login unlock the keyring. bromigos update runs it once for you, and asks for your password through sudo. It adds oo7’s lines to these login settings in /etc/pam.d:

• login, the text console login;
• sddm, the login screen;
• passwd, so a new password carries over to the keyring.

Lines that are already there stay as they are. The setup also turns off KWallet’s own keyring service, so it can’t take oo7’s place. KWallet itself keeps working.

Sign out and in again afterwards. From then on, your login unlocks the keyring.

If sign-in says there’s no keyring

bromigos login checks the keyring before it shows a code, so you never approve a sign-in that can’t be kept. If it says No keyring is running, install oo7 from bromigOS’s repository, set it up, then sign out and in again:

sudo pacman -S bromigos/oo7
bromigos keyring setup

bromigos update installs oo7 too, because the desktop needs it.

If you used gnome-keyring before, pacman asks whether to remove it. Answer y, because oo7 takes its place. The next time you sign in, oo7 moves your saved passwords over.

If it says Your keyring is locked, the keyring is waiting for its password and there’s no desktop here to ask for it. This happens when you sign in some other way, such as over SSH. On your desktop, apps show a password window instead. Type your login password there.

What uses your account

• Setting up a lab offers to put the SSH keys on your account on the new box.

Use another account server

For testing, bromigOS can sign in to another server. Set these in the environment, or in ~/.config/bromigos/accounts.toml under [bromigos] without the BROMIGOS_ prefix, in lower case:

Shell and terminal

bromigOS opens kitty as its terminal and provides a zsh shell setup. The prompt shows where you are and, in a project, its Git branch and language version.

Choose a prompt

Open Settings → Default apps and change Prompt, or run:

bromigos shell prompt mehshell

The choices are mehshell, starship and none. Open a new zsh shell after changing the choice. none gives you a plain prompt with your current folder. Starship needs its package first:

sudo pacman -S starship
bromigos shell prompt starship

New installs use mehshell. Existing installs keep their startup files and prompt. To use the bromigOS choice on an existing install, replace your prompt engine’s initialisation line in ~/.zshrc with this line:

source /usr/share/bromigos/default/zsh/bromigos.zsh

Source it once. Remove any separate mehshell or Starship initialisation first. It also loads bromigOS’s login banner and folder shortcuts.

The choice is saved in ~/.config/bromigos/shell.toml. Your prompt’s other options stay in its own config. mehshell uses ~/.config/mehshell/config.

On Linux text consoles, mehshell uses text labels, simple prompt marks and basic colours. Its startup cache is separate from the desktop’s, so desktop icons do not appear during console login. Your desktop style and icon settings stay saved. Basic terminals (TERM=dumb) receive a prompt without colour formatting.

Clipboard in persistent terminals

Herdr, tmux and GNU Screen can keep running when you leave a text console or restart the desktop. Their old panes may lack the display settings that apps need to paste images. The bromigOS zsh setup recovers those settings at shell startup and before commands run. It discovers the current Wayland socket and, when present, the matching Xwayland display. No display number is hard-coded.

This applies to new commands, including Codex and Claude Code. An already-running app keeps its original environment; exit it and resume its conversation after loading the updated shell setup:

source /usr/share/bromigos/default/zsh/bromigos.zsh

Working display connections, including nested desktops, are preserved. SSH sessions and non-interactive shells are left alone. No clipboard contents are read by the hook. Set BROMIGOS_SESSION_REFRESH=off before sourcing the setup to disable recovery.

Configure and check mehshell

Preview the current prompt at the width of a split terminal:

bromigos shell preview --width 40
bromigos shell preview --style rainbow --width 80

Preview changes no settings. To save a style or brand choice:

bromigos shell configure style lean
bromigos shell configure brand bromigos

Styles are lean, classic and rainbow. Brand choices are auto, bromigos, os and none. Auto shows the bromigOS text badge on bromigOS and the OS icon elsewhere. Text consoles use plain text. These commands configure mehshell without switching your selected prompt engine. Comments and theme colours are preserved.

The prompt adapts to narrow windows. It shortens paths and removes optional details before dropping your current folder or session identity. Git shows changed file counts, ahead/behind counts, conflicts and active operations. wt: identifies a linked worktree. status? means Git could not be read within the prompt’s time or output limit; upstream? means the comparison is unavailable. Counts use local information and never trigger a fetch.

SSH sessions show the user and host; root shows ROOT. A failed command shows a red exit:N, where N is its exit code. This reports a command run in the current shell. Startup checks and the cached prompt do not carry an old failure into a new terminal. Pressing Enter on an empty line or Ctrl+C while editing clears the status. Interrupting a running command with Ctrl+C normally returns code 130 and shows a grey interrupted label.

A small GAME label reflects the local game-mode record. Turn off session, command status or game-mode labels with bromigos shell configure session false, status false or game false, respectively. All indicators use local information.

Check configuration and terminal fallback, or measure slow local prompt segments:

bromigos shell doctor
bromigos shell doctor --timings

--json gives structured output. The doctor reports configuration issues without printing their values. It does not test the installed font’s glyph coverage or inspect your running shell’s hooks. It never queries your lab or prints credentials. Style and segment changes appear at the next prompt; open a new shell after changing hook options or updating mehshell. To load updated hooks in the current zsh shell, run:

eval "$(mehshell init zsh)"

Reloading mehshell keeps one copy of its hooks.

Match the theme

mehshell follows every bromigOS theme. A theme change updates its colours, and its next prompt reads them automatically. Your segment and style options stay in place. Restart zsh after changing instant prompt, transient prompt or vi mode options in mehshell’s config.

Install mehshell

The signed bromigOS package repository at pkgs.bromigos.org includes mehshell. Once that repository is configured, run:

sudo pacman -S mehshell

Other systems can use the installation instructions in mehshell’s repository.

Make text consoles readable

The text console you reach with Ctrl+Alt+F3 has its own font, separate from kitty. Check its saved setting, then choose a size:

bromigos console status
sudo bromigos console font medium

Choose small, medium or large for Terminus glyphs 16, 24 or 32 pixels tall. sudo bromigos console font default removes the saved font choice. The setting takes effect after reboot. The command keeps your keyboard layout and other console settings, and leaves the running console alone.

The bromigos-settings package includes Terminus. On a core-only installation, install it first with sudo pacman -S terminus-font. Text consoles support fewer symbols than a graphical terminal; changing the size does not add Nerd Font icons.

The early boot or disk-unlock screen may still use a font stored in the initramfs until that image is rebuilt separately. This command does not rebuild it. A vconsole.font kernel option also takes precedence over the saved setting. If you have custom FONT_MAP or FONT_UNIMAP settings, review them before choosing a Terminus size; the command refuses to combine them. default preserves them.

Text console login

Text consoles show a green bromigOS banner above the usual login prompt. Sign in with your normal username and password. The password stays hidden as you type.

  +------------------------------------------------------+
  |  bromigOS                               TEXT CONSOLE |
  +------------------------------------------------------+

  Sign in with your username and password.

  After signing in:
    bromigos console status   Check the console font
    bromigos power menu       Restart or shut down

The banner uses ordinary text characters, so it works with the console’s font. If the text is too small, see Make text consoles readable.

After signing in, bromigos power menu opens a keyboard menu for restarting or shutting down. It asks you to confirm the selected action.

Your password also unlocks your keyring, where bromigOS keeps your sign-ins. So a desktop you start from the console doesn’t ask for it again. See Your keyring.

The bromigos-settings package supplies the banner. It appears the next time the console login starts, including after a reboot. Your existing issue message may also appear above it. A custom getty configuration can hide or replace issue messages.

Power menu

Open the keyboard menu from a terminal or a Linux text console:

bromigos power menu

Choose Suspend, Restart or Shut down with the arrow keys, then press Enter. Each action opens a confirmation with Cancel selected. Move to the action and press Enter to proceed. Escape goes back or closes the menu. The keys j/k move through choices; h/l select the confirmation buttons. Tab also moves between choices.

Try the menu without changing the machine’s power state:

bromigos power menu --preview

The menu uses symbols supported by text-console fonts. If the terminal becomes too small, action keys stop working until it is large enough again. Escape still closes it. Normal system permissions and applications’ shutdown inhibitors apply. A refused action reports an error after restoring your terminal.

On the desktop, Alt+Shift+E opens the existing graphical power menu. Both menus request the normal system shutdown or restart. The Plymouth splash provides the closing visuals when graphical splash support is enabled.

Playing games

Install Steam, then press Play. bromigOS keeps everything a game needs to start ready by itself, and tells you only when something needs you.

Steam and Proton

Steam runs Windows games through Proton, a compatibility layer built on Wine. You don’t need to know how Proton works: bromigOS chooses a good one, keeps it current and repairs what would stop a game from starting.

Get started

1. Open Settings › Playing games and press Set up Steam. A terminal opens and asks for your password once. It installs Steam, GameMode, and the graphics drivers games need for the graphics cards in this computer.
2. Log out and back in.
3. Start Steam, sign in, install a game and press Play.

The first time Steam starts, bromigOS downloads the newest GE-Proton in the background. When you quit Steam, it makes it the Proton every game uses. GE-Proton is a community build of Proton with extra fixes for games and video. It’s checked against the checksum its makers publish before it’s installed.

What bromigOS does for you

After every bromigos update, and each time you quit Steam, bromigOS:

• installs the newest GE-Proton, and makes it the default when the default is missing or an older GE-Proton;
• points a game set to a Proton that isn’t installed any more back at one that is;
• puts the setting that lets Steam install its own runtimes back to Steam’s own value;
• moves a broken Steam Linux Runtime aside, so Steam installs a fresh one the next time you press Play;
• moves old GE-Proton versions that no game uses aside, keeping the newest two.

It never changes Steam’s files while Steam is open, because Steam would write its own settings back when it quits. It never starts or stops Steam. Everything it changes can be undone. Steam’s settings file is copied first, and anything it moves aside is kept for 14 days.

Your choices stay. If you picked another Proton as the default, such as Valve’s Proton Experimental, bromigOS keeps it. A game you set to a Proton that’s installed keeps it too.

Is everything ready?

Open Settings › Playing games. The top of the page says Games are ready, or lists what needs you, each with what to do. Hover over anything on the page to see what it is and does. The page also shows which Proton your games use.

Things bromigOS fixes by itself are listed with when it will fix them. To fix them now, close Steam and press Fix. If a leftover file from an older bromigOS set-up still changes your login screen, Fix asks for your password to remove it. Updates remove those files too.

When something needs you, such as a setting outside your home folder, you get one notification that says so. You get it once, not every time you quit Steam.

DLSS on NVIDIA

DLSS and Reflex need NVIDIA’s NVAPI, which Proton leaves off unless asked. On NVIDIA’s own driver, bromigOS turns it on for your session with PROTON_ENABLE_NVAPI=1. You need nothing per game.

To swap a game’s DLSS for the newest version Proton has, add this to the game’s Properties › General › Launch Options:

PROTON_DLSS_UPGRADE=1 %command%

Use it per game. Some games check their DLSS files and refuse to start when they change.

With two graphics cards, a game may start on the wrong one. Then DLSS isn’t there and the game may crash. To keep games on one card, choose Games and heavy apps on it in Settings › Graphics, and turn on Start Steam on the games card. For one game only, set its Launch Options to:

bromigos hw run -- %command%

Run games on another card explains both. Underneath, bromigos hw run sets MESA_VK_DEVICE_SELECT=vendor:device, the card’s ID from bromigos hw graphics, such as 10de:2f04. That puts the card first in Vulkan’s list, and DXVK and vkd3d-proton use the first device. bromigos hw run --print shows what it sets.

If you changed the file that holds your session’s graphics settings, ~/.local/state/bromigos/hw/hyprland.lua, bromigOS leaves it alone and doesn’t turn NVAPI on. Settings › Playing games says so. To hand the file back to bromigOS, run:

mv ~/.local/state/bromigos/hw/hyprland.lua ~/hyprland.lua.mine
bromigos hw setup --user-only

Then log out and back in. Your own version stays in ~/hyprland.lua.mine.

Game mode

Game mode gives the focused game your keys, including Alt, Ctrl, letters and F-keys. It quiets notifications, stops idle locking and sleep, pauses the live wallpaper and hides panels (widgets). The bar shows GAME MODE.

Press Super+Ctrl+G to turn it on. Press Ctrl+Shift+F12 to leave. An on-screen message confirms entry and exit. The escape key appears when you enter. It is the only desktop shortcut that works during game mode. Leaving restores your previous notification state, panels and wallpaper behaviour.

You can also use Settings › Playing games or these commands:

bromigos game on
bromigos game off
bromigos game toggle
bromigos game status

If you need to recover from a TTY or SSH, run bromigos game off as your normal user. The keyboard escape resets the shortcut mode even if the helper cannot answer.

Your keyboard’s Game Mode key

After first installing this feature, log out and back in so the session loads its shortcuts, bar indicator and keyboard helper. Updating alone does not start the helper.

With the Razer keyboard module enabled, OpenRazer’s Game Mode key toggles bromigOS game mode. On a BlackWidow V4 Pro this is Fn+F10. Its gaming LED follows game mode, and turns off when you leave. Use Ctrl+Shift+F12 to leave even if the keyboard has disabled Super. See Keyboards and peripherals.

Automatic mode

Automatic mode is off by default. Turn it on in Settings › Playing games, or run:

bromigos game auto on

It enters when a fullscreen Steam, Windows, gamescope or Lutris game gets focus, and leaves when that game loses focus or stops being fullscreen. Launchers are excluded. Detached native games may need manual mode. If you leave with the escape key, automatic mode waits until focus or fullscreen changes before entering again.

To stop automatic mode, run bromigos game auto off. A game mode you turned on manually stays on when you switch windows.

Battle.net and StarCraft II

Battle.net uses the bar’s tray. Right-click its icon for its menu. After installing a tray-bridge update, log out and back in, then reopen Battle.net.

A Lutris shortcut can launch StarCraft II through an existing Battle.net installation. Set its Wine prefix and executable to the ones used by Battle.net and its arguments to --exec="launch S2". This uses that installation without creating another Wine prefix.

For power users

Everything above as commands, files and rules: to see exactly what bromigOS does, to script it, or to change it.

Every button, as a command

bromigos game setup               # install Steam, GameMode and your GPUs' 32-bit drivers
bromigos game check               # find what stops games from starting
bromigos game check --fix         # fix it now (close Steam first)
bromigos game maintain --dry-run  # what bromigOS would change by itself, changing nothing
bromigos game proton              # the Proton versions here
bromigos game proton install      # the latest GE-Proton
bromigos game proton install GE-Proton10-25   # one version
bromigos game proton remove GE-Proton10-25    # remove one (close Steam first)
bromigos game maintain            # the upkeep now: the newest GE-Proton, and Steam's files if Steam is closed

game setup --dry-run shows what setup would install. Steam needs the multilib repository, which holds 32-bit packages. If it’s off, setup says how to turn it on and stops.

game proton install downloads GE-Proton from its GitHub releases. It checks the download against the SHA-512 checksum published with it, and throws away a download that doesn’t match. Pick a version for one game in Steam: the game’s Properties › Compatibility. remove won’t remove a version games are still set to, unless you pass --force.

To see what bromigOS did and when, run:

journalctl --user -u bromigos-game-maintain

Settings › Playing games › Log opens the same list.

Script it

• bromigos game check exits 0 when games are ready, 1 when something needs fixing and 2 when it couldn’t check. --json gives each finding, with auto: true on those the upkeep repairs by itself.
• bromigos game setup, game proton and game maintain take --json too. game setup --yes doesn’t ask before it installs.
• game maintain looks for a new GE-Proton at most once an hour. --refresh looks now, --no-download doesn’t look. --wait waits for Steam to exit first, and --notify sends one notification for each new problem only you can fix. The service runs bromigos game maintain --wait --notify.

When the upkeep runs

• After bromigos update: its last step starts the upkeep in the background.
• Each time Steam starts or exits: the systemd user unit bromigos-game-maintain.path watches ~/.steam/steam.pid, which Steam writes as it starts, and ~/.local/share/Steam/config/config.vdf, which it writes as it exits. Either starts bromigos-game-maintain.service, at Nice=10 with idle I/O.
• The GE-Proton download starts at once. Steam’s files change only after Steam has exited and stayed closed for 15 seconds, because Steam restarts itself after its own updates.

How it decides

Steam keeps its tool choices in CompatToolMapping, in config/config.vdf under Steam’s folder (~/.steam/root, else ~/.local/share/Steam). Each entry maps a game’s app ID to a tool, a name and a priority. The entry "0" is the default for every game.

• The default. It becomes the newest GE-Proton when it names a tool that isn’t installed, is unset, or is an older GE-Proton. Any other tool that’s installed stays, such as proton_experimental, proton_9 or a TKG build. With no GE-Proton installed, a missing default becomes proton_experimental.
• The default’s priority goes back to 75. A higher one makes Steam run its own Linux runtimes through Proton, and installing them fails with “Invalid platform”.
• A game set to a missing tool loses its entry, so it follows the default. That’s what unticking “Force the use of a specific Steam Play compatibility tool” does. A game set to a GE-Proton or TKG build that’s gone gets the newest GE-Proton instead. Steam’s own tools count as present, since Steam downloads them itself.
• Old builds. GE-Proton and TKG folders in compatibilitytools.d that nothing uses move aside. The newest GE-Proton and the one before it stay. Links, a package’s tools in /usr/share/steam and other kinds of tool are never touched.
• Versions compare across GE’s naming schemes: Proton-6.21-GE-2 < GE-Proton7-43 < GE-Proton11-11-x86_64.

The files it touches

The developers’ version, with Steam’s file formats, is Steam and Proton.

What the check says

Reinstall a broken runtime by hand

If games quit at once and bromigos game check isn’t at hand:

1. Quit Steam (Steam › Exit).
2. In the Steam library that holds the runtime, delete the runtime’s folder in steamapps/common, for example SteamLinuxRuntime_4.
3. Delete steamapps/appmanifest_<id>.acf, steamapps/downloading/<id> and steamapps/temp/<id>. The ID of Steam Linux Runtime 4.0 is 4183110.
4. Start Steam and press Play on the game. Steam installs the runtime first.

Installing a runtime from a steam://install/ link doesn’t work. It fails with “Invalid platform”.

Turn off the automatic upkeep

To stop bromigOS from keeping Steam and Proton ready by itself, run:

systemctl --user mask bromigos-game-maintain.service

Updates then leave Steam and Proton alone too. systemctl --user unmask bromigos-game-maintain.service turns it back on.

Storage

bromigos storage helps prepare a local data drive, move files onto it and free space. It separates planning, copying, verification and switching paths. The original files stay available until you decide how to retire them.

See your drives

bromigos storage status

Status groups the mounted folders under each filesystem, with its used space, available space and usage bar. Each filesystem’s capacity appears once. Btrfs subvolumes and bind mounts share that capacity. RAM-backed swap is not listed as a physical drive. Use --json for structured output. Desktop terminals use smooth block bars. Text consoles and redirected output use plain bars so the display stays readable without desktop fonts.

Plan a data drive

Find the stable device name in /dev/disk/by-id/. Check its model, serial number and capacity against the physical drive. Replace <device-id> below with that name and choose one named mount directory directly under /mnt:

bromigos storage plan --device /dev/disk/by-id/<device-id> --mount /mnt/Data \
  --roles development,games,downloads,vms,models

Read the resulting plan before applying it. Preparing a drive is destructive. Back up anything you need from that device first. Existing disks are not a substitute for a backup of important data.

When the device and plan are correct, apply it yourself in a terminal. Use the absolute plan-file path printed by planning, since root uses a different home directory:

sudo bromigos storage apply /absolute/path/to/plan.json

Applying asks you to type the exact disk serial number in your terminal. It erases the whole disk, creates one GPT partition, mounts the filesystem and writes its mounts to /etc/fstab. If it fails, inspect the journal before trying anything else. The same erase plan cannot be applied twice.

The data filesystem is Btrfs. Each selected role gets a separate subvolume, which is a folder Btrfs manages independently. Roles share the drive’s free capacity. They do not reserve space or impose quotas. VM storage can fill the same free space used by other roles. This flow does not configure encryption or automatic snapshots.

The development role comes first and mounts at /mnt/Data itself. Other selected roles mount under it as /mnt/Data/games, /mnt/Data/downloads, /mnt/Data/vms and /mnt/Data/models. VMs are owned by root; the other role roots belong to the user who created the plan. Choose roles explicitly when you need fewer of them.

Copy files before switching

Plan a copy with explicit source and destination directories:

bromigos storage migrate plan --source /path/to/source --destination /mnt/Data/projects

Keep the displayed plan ID and absolute saved-plan path. Copying preserves owners, permissions and extended attributes, so run it with administrative access. Then verify it and read its status:

sudo bromigos storage migrate run /absolute/path/to/plan.json
sudo bromigos storage migrate verify /absolute/path/to/plan.json
bromigos storage migrate status <plan-id>

A copied directory has not necessarily been verified. Verified files have not necessarily replaced the paths your applications use. Check the recorded stage before continuing.

If copying stops, inspect its status and resume the same plan:

sudo bromigos storage migrate resume /absolute/path/to/plan.json

For several moves, write a TOML file and use --spec /path/to/moves.toml instead of --source and --destination:

[[move]]
source = "/path/to/source"
destination = "/mnt/Data/projects"
keep_path = "/path/to/source"

keep_path is optional. Set it when applications must keep using an existing path. Switching requires at least one such path. For a copy without one, verify the copy and update your application’s storage setting yourself. If it is the source path, switching retains the original as <source-name>.before-storage-<plan-id> beside the old directory and places a bind mount at the old path. A bind mount makes the destination appear at that path. Without keep_path, the original path stays as it was; update your applications to use the destination yourself.

Stop every application or service that writes to the source before the final verification and switch. Log out of all graphical sessions and use a text console for the switch. Keep writers stopped while switching. The original copy is retained for recovery; the switch does not make a backup unnecessary. The command does not stop applications, services or graphical sessions for you. It refuses the switch while processes still use the affected paths. Once writers are stopped, switch using the absolute saved-plan path:

sudo bromigos storage switch /absolute/path/to/plan.json --writers-stopped

The command asks you to type SWITCH and the plan ID in your terminal. It performs a fresh final copy and checksum comparison before changing paths. Inspect the journal after any failed or interrupted switch before trying to continue. A switch in progress or marked switch-failed cannot be replayed automatically. Its journal lists retained source paths and the saved fstab file for manual recovery. Do not delete the old directory merely because the destination exists.

Review cleanup and snapshots

bromigos storage cleanup --preview

The preview lists supported cache locations and local snapshots managed by Snapper and btrbk. It shows when a provider cannot be inspected; run the preview with sudo if it reports access restrictions. Preview removes nothing. Snapshot counts and file sizes are not promises of space reclaimed. Other snapshots can still hold the files after originals are deleted.

Clean downloaded caches

Create a plan for the npm and Conda caches you want to clear. Repeat --cache to select both, or include only the cache you need:

bromigos storage cleanup plan --cache npm --cache conda

Read the plan, then use its printed absolute path to apply it. Run these user cache commands as yourself, without sudo:

bromigos storage cleanup apply /absolute/path/to/cache-plan.json

npm cleanup clears downloaded package content in ~/.npm/_cacache. Conda cleanup clears downloaded archives, index data and logs in ~/.conda/pkgs. Extracted Conda packages and environments remain available. The total cache size shown by preview can include files these actions keep. If Conda resolves additional cache locations, cleanup stops so they can be reviewed.

For downloaded system package archives, make a separate plan:

bromigos storage cleanup plan --cache package-archives --keep-versions 3
sudo bromigos storage cleanup apply /absolute/path/to/package-cache-plan.json

Replace the apply path with the one printed by planning. Package cleanup keeps three cached versions of each package by default. You can choose a different count with --keep-versions, from 1 to 100. It does not uninstall packages.

User caches cannot share a plan with system package archives, retained originals or snapshots. Applying any cleanup plan asks you to type CLEANUP and its plan ID. Add --yes when applying an already reviewed plan to skip that prompt. Results and errors are logged, with actual available space measured before and after cleanup.

Retire migrated originals

After a successful switch, create a cleanup plan for its retained originals:

sudo bromigos storage cleanup plan --migration /absolute/path/to/migration-plan.json

Planning records the exact directories without deleting them. It accepts completed switches made by this CLI. External scripts and their records are not imported. Copy-only sources are kept because they may still be in use.

Close applications and services using the affected data before applying the cleanup. Keep them stopped until it finishes. The command checks open files, working folders, mounts, fstab and checksums. If active files have changed since switching, it keeps the original and lists differences for review. It never overwrites the active copy.

Use the absolute cleanup plan path printed by planning:

sudo bromigos storage cleanup apply /absolute/path/to/cleanup-plan.json

It asks you to type CLEANUP followed by the plan ID. For an already reviewed plan, add --yes to skip that confirmation. Administrative authentication can still be required. Original-copy deletion cannot be undone by this command.

Remove selected snapshot history

Copy an exact snapshot path from the cleanup preview. You can repeat --snapshot to select several paths in one plan:

sudo bromigos storage cleanup plan --snapshot /absolute/path/to/snapshot

Read the plan, then apply it using the same cleanup apply command above. Deleting a snapshot removes that rollback point. Only the listed local snapshots are selected; NAS backup streams and other snapshots are kept. Removing btrbk source snapshots can make its next backup send a full copy. Root snapshots are included only if you explicitly select their paths. Snapshot cleanup is never inferred from the amount of free space.

The command waits for Btrfs to finish removing the selected snapshots, reports actual available space before and after, and lists remaining snapshots. A snapshot created while cleanup runs is reported for separate review. It is not automatically deleted.

Read cleanup progress and errors

sudo bromigos storage cleanup status /absolute/path/to/cleanup-plan.json

For a user cache plan, run cleanup status without sudo. Each attempt saves a private log beside the plan, including errors. Status shows the log path, completed actions and available-space measurements. Add --json for the full record. If checks failed before deletion, address the reported problem and retry the same plan. If deletion started and then failed or was interrupted, inspect the log and completed paths before making a new plan. The command refuses to replay a partial deletion automatically.

Apps

bromigOS runs any Linux app. This page covers installing apps, choosing which apps open your files, and the optional app bundle: a set of apps already set up in bromigOS’s style.

Install an app

1. Open the menu with Super+Space and type package.
2. Choose INSTALL › Package….
3. Type the package’s name and press Enter. A terminal opens, installs it, and stays open so you can see the result.

Or in a terminal, with Arch Linux’s package manager:

sudo pacman -S firefox

To remove an app, choose REMOVE › Package… in the menu, or run sudo pacman -Rs and the package’s name.

Install an app from the AUR

The AUR, the Arch User Repository, has recipes for software that isn’t in Arch Linux’s own repositories. A helper called paru fetches a recipe, builds the app on your machine and installs it. bromigOS installs paru for you, unless you said no at the first run.

paru -S cbonsai

Anyone can submit a recipe to the AUR, and nobody checks it first. A recipe runs commands on your machine when it builds. So before paru builds anything, it shows you the recipe, or what changed in it, and asks whether to go on. Read it, or only install apps whose maintainers you trust.

bromigos update updates your AUR apps too, after everything else. See Packages from the AUR.

To leave the AUR out altogether, run bromigos aur off. bromigos aur on brings it back. The developer docs’ aur.md has the details.

A new app appears in the app launcher and the menu straight away. Some launchers keep a cache, and show it the next time they open.

Choose which apps open your files

Open Settings › Default apps. Choose the app that opens links, folders, text files, Markdown notes, pictures, videos, music, PDFs and email. The same page chooses the terminal and file manager that bromigOS’s keys open.

For Markdown notes, a notes app such as Zettlr fits well. bromigOS doesn’t install one, but every theme colours Zettlr. See Themes and worlds.

Keep a website as an app

See Web apps.

A start page for your browser

bromigOS keeps a browser start page up to date for you, in your theme’s colours. It has a search box, your links, your homelab’s status, your latest field notes and a clock.

1. In your browser’s settings, set the home page to file:///home/YOU/.local/share/bromigos/startpage/index.html, with your user name in place of YOU.
2. To change the links, edit ~/.config/bromigos/startpage.toml.

In Chromium-based browsers, you can also load the same folder as a new-tab extension.

The app bundle

bromigos-apps is an optional set of apps with bromigOS’s settings. Where the theme can reach them, they take its colours.

To install the bundle:

1. Run bromigos install --with bromigos-apps, or sudo pacman -S bromigos-apps.
2. Run bromigos apps setup. This puts the apps’ settings files in place, only where you don’t have your own.

Your own settings for these apps

Your Neovim and tmux files are short. They load bromigOS’s settings first, so you add yours after them. For Neovim, add plugins in ~/.config/nvim/lua/plugins/, the LazyVim way.

lazygit, mise and Chromium can’t load another file, so you get a copy of bromigOS’s settings. From then on the copy is yours, and updates don’t change it.

Web apps

A web app is a website in a window of its own, without the browser’s tabs and address bar. It’s in the app launcher like any other app, and it can have its own key.

Add a web app

1. Open the menu (Super+Space) and choose INSTALL › Web app….
2. Type a name for it, such as gmail.
3. Type the site’s address, such as https://mail.google.com.

The web app is now in the app launcher (Alt+P).

Some are ready-made. The menu’s INSTALL group lists them, such as Web app: Gmail and Web app: YouTube. Choose one to add it.

Sign in

A web app uses your browser’s profile. Sign in to the site in your browser first, and the web app is signed in too.

The window opens in the first Chromium-based browser it finds, in this order: Chrome, Chromium, Brave, Vivaldi, Edge. Without one, it uses LibreWolf, Firefox or Zen. These have no app windows, so the web app opens as a normal browser window.

Give it a key

Add --hotkey when you add it from a terminal:

bromigos webapp add gmail https://mail.google.com --hotkey "SUPER + SHIFT + G"

Or give an existing web app a key in Settings › Shortcuts. See Your own shortcuts.

From a terminal

bromigos webapp catalog                     # the ready-made ones
bromigos webapp add --from-catalog youtube  # add a ready-made one
bromigos webapp list                        # yours
bromigos webapp remove gmail                # remove one, and its key

A web app uses the site’s own icon. To choose another, add --icon and a file or an address.

Remove a web app

Open the menu and choose it under REMOVE, or run bromigos webapp remove and its name.

Your media

Find a show, film or album, download it to your own library, and watch it on your media server or the desktop’s den TV. You can use commands, the terminal’s media library, or VECTOR, the desktop’s AI assistant.

Your homelab needs the matching services connected first: Sonarr for shows, Radarr for films and Lidarr for music. Seerr can handle requests too. Pinchflat downloads YouTube. Jellyfin or Plex plays the files.

Get a show, film or album

From the Media app

Open bromigos media, then choose Search or press 7 or Ctrl+F. Type a title, choose Films, TV, Anime or Music, and press Enter or the Search button. Search includes media you do not have yet. The Have it column shows existing matches. Press Enter on a result to choose what to request, its quality and audio languages. Searching alone does not download anything. / filters titles already in your library.

From a terminal

Find the right title first:

bromigos lab media search "Cowboy Bebop" --anime
bromigos lab media search "Dune" --movie
bromigos lab media search "Daft Punk" --music

Each result has an ID, a year and a kind. Use that ID if several titles share a name. For music, the results can be artists or individual albums. An artist request gets its albums; an album request gets just that album.

To request a show, including its specials, at up to 1080p with English audio:

bromigos lab media get tv:tvdb:76885 --seasons all --specials --quality 1080p --audio en
bromigos lab media get "Dune" --movie --quality 1080p --audio en
bromigos lab media get "album:<musicbrainz-id>" --music

The command shows the title, quality profile, audio rule, estimated size and free space. Read the plan, then confirm. It requests the download and keeps watching for missing files. A quality profile is your server’s rule for which releases it accepts.

For the album, replace <musicbrainz-id> with the album ID from search. For another title, replace tv:tvdb:76885 with the ID from search. You can also use a name with --tv, --movie, --anime or --music.

• Pick seasons with --seasons 1,3, a range such as --seasons 2-4, or --seasons latest.
• Pick episodes with --episodes S02E05,S02E06.
• Use --seasons future to wait for new episodes without fetching old seasons.
• New episodes and seasons are monitored by default. Add --new no to stop that.
• --quality best uses the best profile your server offers. 2160p, 1080p and 720p set a ceiling. Your server still needs a suitable profile.

For every option, see the media command reference. bromigos media get … is another spelling of bromigos lab media get ….

Choose your audio language

Audio rules apply to films and shows, including anime. To require English and favour a second Japanese track when available:

bromigos lab media language set en ja
bromigos lab media language anime same
bromigos lab media language required yes
bromigos lab media language subtitles en
bromigos lab media language show

The first language is required. The others are welcome as extra tracks. Subtitles are a separate choice. --audio en changes one request, while these commands save your defaults. You can change them in Settings › Lab too.

Your server’s profiles must enforce the rule. If they cannot, the request plan warns you. Check that warning before confirming. The reference explains language profiles.

Track something that is not out yet

Search for the title and request its ID as usual. A film request uses --when released by default: it waits for the home release. It does not ask for a cinema recording. Shows can monitor future episodes with --seasons future.

The title appears in Upcoming, with the release dates your server knows. A title with no date stays monitored; requesting it cannot make a release arrive sooner.

Use the media library in the terminal

bromigos media

Choose Search, or press 7 or Ctrl+F. Search, pick a result and choose its seasons, quality and audio. The form previews the request automatically and updates it when you change an option. Read the title, scope, quality and space estimate, then choose Request. That button stays unavailable until the current preview is ready. Preview reads the plan again.

After you confirm, Requesting… appears and the form waits for the result. Its controls stay locked while your media service handles the request. A successful request closes the form. An error stays visible in the form so you can review it.

The TV, Movies and Music tabs show what you have. Use arrows or j, k, h and l to move. Pick a show to see its seasons, or an artist to see its albums. Press P to change its profile, m to change monitoring, or f to search now. On the top tabs, Left/Right or h/l selects the previous or next tab. Press Down or j to enter the table. At its first row, Up or k takes you back. Press ? for keyboard help. Press Ctrl+C to quit from the main screen. In a dialog, Escape or Ctrl+C cancels an unconfirmed dialog and returns to the library. Letters such as q stay available while typing. A dialog keeps the background tabs and actions inactive. See the library’s keys for the full list.

Ask VECTOR

Press Super+E and ask, for example:

• “Get season 2 of this show, up to 1080p, with English audio.”
• “Find this album and show me what you would download.”
• “Track this film and get it when the home release comes out.”

Give the title and year if there could be several matches. VECTOR tells you what he found and the plan. He asks before requesting unless you clearly asked him to download one title. You can also ask what is missing or when it will arrive.

See what is downloading or coming up

bromigos lab media status
bromigos lab media status "Cowboy Bebop"
bromigos lab media upcoming --days 30
bromigos lab media recent --hours 24

status shows progress, time left and failures. A season pack’s size and speed are counted once, even when it covers several episodes. Stalled torrents, paused downloads and torrents waiting for their details are labelled separately from active downloads. A stalled torrent with no connected seeders says so. A title’s status adds its seasons, monitoring, file languages and subtitles. upcoming lists what you track, with its known dates. recent lists files that reached the library.

In bromigos media, use Downloads or Upcoming. You can also ask VECTOR, “What’s downloading?” or “What’s coming up this month?”

Delete safely

Pick the smallest thing you want to remove. To delete one season:

bromigos lab media delete "Cowboy Bebop" --season 1

It shows which files will go and how much space that frees. Type the title to confirm. Deleting is permanent. Cancel if the scope or title is wrong.

Without --season, it deletes the whole title and its files. --episodes picks episode files. For music, --album picks one album from an artist. --exclude keeps a whole removed title or album from being added back by an import list. A removed season or episode stops being monitored.

In the terminal library, select the title, season or album and press D. Read the question, then choose Delete or Cancel. Cancel is selected first; Escape or Ctrl+C cancels. Don’t fetch it again adds the import exclusion. To keep files and only stop looking for more, use m instead. The delete reference explains the scopes.

The delete dialog starts on Cancel. Left/Right chooses a button and Enter activates it. Up/Down moves to or from the exclusion checkbox; Enter or Space toggles it. Tab and Shift+Tab also move between controls. Escape or Ctrl+C cancels.

Keep YouTube channels and playlists

To download new uploads from a channel into your library:

bromigos lab youtube add https://www.youtube.com/@NASAGoddard --since 2025-01-01 --quality 1080p
bromigos lab youtube list
bromigos lab youtube status

A playlist address works too. Pinchflat keeps its order. --since skips older uploads. To pause a source, run bromigos lab youtube pause "<source-name>". Replace <source-name> with its name from list. resume starts it again, and refresh checks for new videos now.

bromigos lab youtube remove "<source-name>" asks before removing a source. Its videos stay on disk. Add --delete-files only when you want to remove the files too.

To make downloaded playlists appear in Jellyfin or Plex in YouTube’s order:

bromigos lab youtube sync --dry-run
bromigos lab youtube sync

The first command previews changes. The second applies them. See YouTube downloads for quality, sign-in cookies and every command, and connection settings.

Watch on the den TV

The den is the default theme’s wallpaper: a radio room with three live screens. Each screen can play a different channel from your library, YouTube or a folder of videos.

1. Open the guide with Super+Alt+G, GUIDE in a screen’s hover controls, or Settings › Den TV.
2. Choose Add channel…, then Shows or movies you pick. Search your library and select the posters you want. Pick the order and give the channel a name.
3. Choose BIG, SCOPE or SMALL on its card to put that screen on the channel.
4. Click a playing screen, or FULL, to watch full screen with sound. Close the player to return to the desktop.

For a Night Block, make a channel with that name and pick the shows for your evening. Choose in order or shuffle. Turn on Bumpers in its menu for short cards between items. This is a channel you make, not a preset schedule.

The screens start silent. Turn sound on with the speaker in a screen’s controls. Only one screen has sound at a time. Channel 1 restores that screen’s normal picture. For all controls and channel settings, see The den TV.

Make channels for the den TV

In bromigos media, choose Channels or press 8. Each channel shows its kind, play order, bumpers and the screens on it now. Select one to see its titles and what’s on now and next. A library channel includes everything in its library. A picked channel holds the shows, movies, YouTube addresses or music you choose.

From TV, Movies, YouTube or Music, select a title and click Add to channel… (c) below the list, or press c. This also works on Search results, Downloads and Upcoming titles. In Music, selecting an album adds that album. Choose Add to Night Block (or another picked channel), then Apply channel choice. You can also choose Remove from… or New channel….

A small diamond marks titles already in a channel. Select or hover over a title to see its channel names. The names also stay visible beside Add to channel…. The picker lists its current channels and marks Already in … — remove.

Adding something to a channel does not download it; it must be available from the media server or YouTube. Music plays through the den’s sound controls.

On Channels, Ctrl+N adds a channel, F2 renames it, v changes its order, and b switches bumpers. Select a picked item and use Alt+Up or Alt+Down to reorder it, or x to remove it. From the channel list, the same arrows move the whole channel. D asks before deleting a channel. Ctrl+Z restores the last deleted channel. Tune, or c on this tab, chooses a screen.

Removing a pick or a channel keeps the media files. Each change shows a confirmation message, preserves comments in the config, and reaches the den without a restart. The Den TV app offers the same channels in a window with posters.

Use commands or ask VECTOR

To see the channels and add a show:

bromigos-live tv channels --json
bromigos-live tv channel add "Night Block" --shows "Example Show" "Another Show" --order alternate --bumpers
bromigos lab media channel add "Example Show" --to "Night Block" --json

Names work wherever a command asks for a channel. The numbers in tv channels are positions in the config. Screen numbers are separate: channel 1 is each screen’s own picture. channel tune finds the right screen number from the name.

bromigos-live tv channel add-item "Night Block" "Example Film" --kind movie --json
bromigos-live tv channel remove-item "Night Block" "Example Show" --json
bromigos-live tv channel move-item "Night Block" "Another Show" 1 --json
bromigos-live tv channel order "Night Block" shuffle --json
bromigos-live tv channel bumpers "Night Block" off --json
bromigos-live tv channel rename "Night Block" "Evening" --json
bromigos-live tv channel move "Evening" 1 --json
bromigos-live tv channel tune "Evening" --screen wave --json
bromigos-live tv channel remove "Evening"
bromigos-live tv channel undo --json

remove asks you to type the channel name. Scripts can pass --yes. All channel commands accept --json. Exit codes are 0 for success, 1 for an operation that failed, 2 for invalid arguments or a missing confirmation, 3 for a conflicting name, and 4 for something not found. tv channels --refresh reads library contents from the servers; without it, now/next and contents use the local cache.

Ask VECTOR, the desktop’s AI assistant, “Add this show to Night Block”, “What’s on the den TV?”, or “Tune the scope to Evening”. From the phone he can read channels and add or remove individual picks. Creating channels, tuning screens and deleting whole channels stay on the desktop. A whole-channel delete needs your explicit request naming it. The command reference and bromigos-live tv channel --help list the options for libraries, YouTube and folders.

Put releases on your calendar

Open the CALENDAR panel’s Settings… and turn on Your media server’s releases. It adds tracked TV episodes and film releases from Sonarr and Radarr to your other events. It needs those services connected through Your homelab.

You can show the panel from Customize › Widgets, or run:

bromigos panels show calendars

See Calendar releases for the setting and feed export.

If something goes wrong

Nothing was found or nothing is downloading

Search with the kind and year. If the name is ambiguous, use the result’s ID. A title can exist in the catalogue before there is anything to download.

For a tracked title, ask the indexers now:

bromigos lab media status "Cowboy Bebop" --why
bromigos lab doctor

The first command explains missing releases and rejections. The doctor checks whether the connected services answer. A release can be rejected for quality, language or a profile’s minimum score. Check those rules before relaxing them.

The audio is in the wrong language

Use language show and the title’s status to compare your request with the files. Check the selected profile in Sonarr or Radarr. Changing the defaults does not rewrite files you already downloaded. Pick the right profile and search again; keep the old files until you have checked the replacement.

Jellyfin cannot play a file

Check that Jellyfin can see the media folder, and that its container has the right permissions. Check the media server’s logs for missing files or transcoding errors.

If several media apps freeze while the NAS still answers, its client may have a stuck NFS lock connection. Ask the lab administrator to check it through the lab’s maintenance procedure. See Media files on a NAS.

Play something on a den screen

Press p in the media library to open Play on den TV. Choose BIG, SCOPE or SMALL. Pick a show, then its season and episode, or choose a movie. The YouTube view lists downloaded videos; you can also search with a YouTube video URL. Turn Resume where you left off on to use the server’s saved position. Otherwise playback starts at the beginning. P changes a quality profile.

The Den TV app has a Play… button for each screen with the same choices. The screen shows ON DEMAND while your choice plays. When it ends, or you change channel, the screen returns to its channel’s live schedule.

bromigos-live tv play --screen big "Cowboy Bebop S01E05" --json
bromigos-live tv play --screen scope --id ITEM_ID --source SERVER_NAME --resume --json
bromigos-live tv play --screen small --url "https://www.youtube.com/watch?v=VIDEO_ID" --json
bromigos-live tv search "Cowboy Bebop" --kind shows --json

SERVER_NAME is a source name from your media settings. Use --id when titles are ambiguous. Search with --kind seasons --id SHOW_ID, then --kind episodes --id SHOW_ID --season 1 to list episodes. Ask VECTOR to “play Cowboy Bebop episode 5 on the big TV.” See the den controls for sound, full screen and the number-pad remote.

Cast to another screen

bromigos media cast plays a title, or what a den screen shows, on another screen in the house: a Chromecast or Google TV, a smart TV that is a DLNA player, an Apple TV or AirPlay TV, or a TV or phone running Jellyfin’s app. The den’s own screens are on the same list.

bromigos media cast targets                                   # every screen it finds, and what each plays
bromigos media cast play --target "living room" --title "Cowboy Bebop S01E05"
bromigos media cast play --target "living room" --screen big  # what the big den screen shows, from the same moment
bromigos media cast control --target "living room" pause      # play, pause, stop, seek 600, volume 40, mute
bromigos media cast status --target "living room"
bromigos media cast handback --target "living room" --screen big   # back to the den, from where it was

--target takes a target’s id from the list, or words from its name, room or kind, such as living room, bedroom tv or chromecast. Each command takes --json. bromigos media cast targets --dry-run only lists what it finds and keeps nothing.

• Where it looks. Only your own network: mDNS and SSDP ask the devices nearby, and Jellyfin lists the apps it can steer. A firewall on this computer must let mDNS (UDP 5353) and SSDP (UDP 1900) answers in.
• How a TV gets the video. The TV fetches it from your media server itself. If the server’s address uses your lab’s own certificate authority, which TVs don’t trust, set cast_url on the source to an address they can reach (see the media sources). That address carries the server’s key, so it’s given only to the TV, never shown or logged.
• What can’t be cast. Files only on this computer, and streaming apps’ protected video (Netflix, Disney+, Prime Video and the like): start those from the app on the TV.
• A record. Every play, control and hand back is a line in ~/.local/state/bromigos/cast-audit.jsonl: when, who asked, which screen, what played. Addresses and keys are never in it.

Ask VECTOR to “play Cowboy Bebop on the living room Chromecast”, or “move it back to the den”. BRODEC’s den remote on your phone picks targets from the same list, through the machine agent on this computer.

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.

The lab console

bromigos lab is the console for your homelab. It shows what the lab is doing and what its graphics cards hold, runs AI jobs on them, and checks the lab for problems. It reads the services you connected. Anything your lab doesn’t have is simply not shown.

Connect a homelab first with bromigos-lab connect, or bromigos setup homelab on bromigOS.

Install on plain Arch

The bromigos-lab AUR package runs without the bromigOS desktop. It includes the terminal dashboard, service adapters, model catalog and provisioning. With an AUR helper, run paru -S bromigos-lab. Without one:

sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/bromigos-lab.git
cd bromigos-lab
less PKGBUILD
makepkg -si

Read the recipe before building it. It uses a pinned source release and a SHA-256 checksum. It installs the console without changing your desktop or system settings. Connect your services and check them:

bromigos-lab connect
bromigos-lab doctor
bromigos-lab

Replace bromigos lab with bromigos-lab in the commands on this page. Both use ~/.config/bromigos/homelab.toml and the same lab state. Provisioning asks for an explicit yes before changing machines. Install the optional tools listed by pacman -Qi bromigos-lab for the services and providers you choose.

On bromigOS, bromigos-homelab pulls in this package and keeps bromigos lab working. Its desktop panels, live decks and VECTOR plugins are separate integrations. Desktop target commands, art jobs and the Den TV media screen need the optional bromigos-core package. The main console, adapters and provisioning run without it.

Rack maintenance

Use bromigos lab maintenance when you need to shut the lab down for rack work and bring it back afterwards. Do not unplug a running NAS or a machine writing database files. A machine that stops answering the network is not proof of a clean shutdown. Keep power connected until its own management screen or physical indicators confirm that shutdown finished.

You can read the configured health checks first:

bromigos lab maintenance check

These checks report service problems. They do not verify backups or prove that equipment is powered off. Start by saving a plan. Planning does not power anything off:

bromigos lab maintenance plan shutdown
bromigos lab maintenance status

Read the plan and keep its ID. To follow it interactively, replace <plan-id> with that ID:

bromigos lab maintenance run <plan-id>

The default plan is a guided checklist. Read each instruction, complete it yourself, then type done followed by the displayed step ID. Any other answer pauses the run. The run asks for yes before it starts. --yes can skip that initial question, but cannot acknowledge manual steps or make them work without a terminal. Acknowledging a manual step records your check; it does not turn it into a machine-verified result. Keep recovery instructions and credentials available somewhere that remains accessible while the lab is off.

Shutdown follows dependencies. First check backups and recovery access, then finish any operator-controlled services. Stop jobs, games and other writers before compute workers. Stop the cluster’s control plane before its hypervisor, then the NAS. Keep network equipment available until everything that needs it is safely off.

Startup brings the network and storage back first. Wait for storage to be ready before starting hypervisors, the cluster, workers and applications. Check each dependency before continuing. Restart services that need the operator’s approval yourself.

If you stop partway through, use the run ID to continue from its journal:

bromigos lab maintenance resume <run-id>

When the rack is reconnected, create and follow a new startup plan:

bromigos lab maintenance plan startup
bromigos lab maintenance run <plan-id>

An optional private profile supplies instructions and reviewed Ansible playbooks for your own hardware. Select a configured profile with --profile <name>, or use --profile-file <path> when planning. Keep machine names, addresses and credentials out of shared configuration. The contributor reference explains the profile format.

Plans and run journals stay in ~/.local/state/bromigos/lab/maintenance/. A completed checklist records your confirmations. It does not certify that every device is off. If a runbook fails or is interrupted, inspect the hardware before doing anything else. Resume refuses to repeat a step whose result is uncertain. Create a new reviewed plan after inspecting that state.

PDU power

A power distribution unit (PDU) can report and switch individual rack outlets. bromigos lab power status shows the labels, outlet states and electrical readings available from your configured controller, including the reported total load:

bromigos lab power status

Missing watt, volt or amp readings show as unknown. They do not mean the connected equipment uses no electricity. An outlet shared by several devices measures their combined load. A new PDU needs to be installed, adopted and configured before these readings are available.

Shut the operating system down cleanly before switching its outlet off. An outlet turning on supplies electricity; the machine only boots automatically if its firmware is configured to do so. Outlet numbers do not establish a safe shutdown or startup order. Use the rack maintenance flow for work on the whole rack.

Power changes require a named target connected to a private maintenance profile. To preview an outlet change, replace <target> with that configured name:

bromigos lab power plan <target> off

Read the plan, verify its outlet and connected equipment, and complete its shutdown checkpoints before running it. Replace <plan-id> with the displayed plan ID:

bromigos lab power run <plan-id>

Use plan <target> on for a startup plan. A paused run can continue with bromigos lab power resume <run-id>. Plans and runs use the same confirmations and journals as maintenance. Planning alone never switches power.

Look at your lab

Run bromigos lab for the live dashboard. It refreshes every 15 seconds.

You can quit while a refresh is running. Queued and running jobs continue after the dashboard closes; use the Jobs tab to cancel a job explicitly.

To move around, use the arrow keys or Vim’s keys:

The focused list or control has a highlighted border. The buttons and footer show actions for the current tab. Use Tab or Shift+Tab to move between controls. At the tab bar, h and l switch tabs; Down or j enters the list. At the first row, Up or k returns to the tab bar.

To cancel a job, press c on Jobs and read the question. Keep job is selected first. Choose Cancel job only if you want it stopped. In any dialog, Escape or Ctrl+C closes an unconfirmed dialog without applying the pending change. Arrow keys move between controls and Enter activates the selected button. Background tabs stay inactive. Letters such as q can still be typed into a form.

Hover over anything for what it is.

Or print the same information:

bromigos lab status           # one line for each part of the lab
bromigos lab models           # what each graphics card and model server holds
bromigos lab doctor           # what's wrong, and how to fix it

As a hologram

Press Super+Shift+H for the lab deck: your lab as a server rack, lit by the same readings. See Holograms.

In Settings

Settings › Lab shows the same summary, your models, recent jobs, the doctor, and where AI runs.

Make things on your lab

Send a job to your lab’s graphics cards:

bromigos lab run image --prompt "a lighthouse at dusk"
bromigos lab run cutout --input ~/Pictures/robot.png
bromigos lab run upscale --input ~/Pictures/robot.png --scale 2
bromigos lab run hologram --prompt "a brass telescope"
bromigos lab run voice --text "The relays are lit."
bromigos lab run transcribe --input ~/Downloads/talk.m4a

bromigos lab run --kinds lists what your lab can do, and says why when it can’t do something.

When a job is done, a notification tells you. The result goes in ~/Pictures/bromigos/lab/, in a folder for each kind of job.

You can also ask VECTOR for a picture, a hologram or a voice line “on the lab”. His jobs show in the queue as his.

The job queue

bromigos lab jobs              # what's queued, running and done
bromigos lab jobs watch        # follow the queue until it settles
bromigos lab jobs cancel ID    # cancel a job
bromigos lab jobs retry ID     # run a job again

Jobs take turns. One heavy job runs at a time, and only when a graphics card has room for it. VECTOR’s voice always keeps its share. A job that has to wait says why.

It’s free unless you say otherwise

Jobs run on your lab, which costs nothing. A paid cloud service is only used for a job if you add --cloud to it.

Models

bromigos lab models                   # what each machine holds
bromigos lab models load NAME         # load an Ollama model
bromigos lab models unload comfyui    # free what ComfyUI holds
bromigos lab models recommend         # better models that fit your graphics cards

YouTube downloads

For finding, downloading and watching media, start with Your media.

If your lab runs Pinchflat, it downloads YouTube channels and playlists into your media library. Then they play in Jellyfin or Plex, like your other shows. You can run it from here without opening its web page.

Add a channel or a playlist

bromigos lab youtube add https://www.youtube.com/playlist?list=PLCFE9837C2F7EB8AA
bromigos lab youtube add https://www.youtube.com/@NASAGoddard --since 2025-01-01

It says what it will download. A playlist keeps its order. A channel gets every upload.

• It works out from the address whether it’s a playlist or a channel. If it can’t, add --playlist or --channel.
• --since 2025-01-01 skips videos uploaded before that date. It’s worth it for a big channel.
• --name NAME sets its name in Pinchflat, on disk and in your media server.
• --quality sets the most it downloads. See below.

In the dashboard (bromigos lab), the YouTube downloads card has an Add a channel or playlist… button. It does the same thing. The key is a.

Look after them

bromigos lab youtube list                      # each one: kind, quality, videos, last check, newest video
bromigos lab youtube status                    # the download queue, failures, recent downloads
bromigos lab youtube refresh "Little SDO"      # check for new videos now (leave out the name: all of them)
bromigos lab youtube pause "Little SDO"        # stop checking and downloading; resume starts it again
bromigos lab youtube remove "Little SDO"       # stop downloading it; the videos stay
bromigos lab youtube remove "Little SDO" --delete-files   # and delete its videos too

remove asks before it does anything. Your videos stay on disk unless you add --delete-files. After a removal, the playlist in Jellyfin and Plex goes at the next sync.

Every command takes --json.

Quality and disk space

Videos download at up to 1080p unless you say otherwise. Higher quality costs disk space. As a rough guide, for an hour of video:

These come from the sizes YouTube offers for each quality, in the formats Pinchflat picks. Fast-moving or 60-frames-a-second video sits at the top of each range. Talking heads and slides sit at the bottom. best takes the highest a video has, up to 8K.

• add --quality 2160p downloads a new source in 4K.

• bromigos lab youtube quality "Little SDO" 2160p changes an existing one. Only new downloads change. The videos you already have stay as they are.

• To change the default for everything you add, set it in homelab.toml:

  [youtube]
  quality = "1440p"
  

If YouTube asks Pinchflat to sign in

Sometimes YouTube stops a lab’s downloads with “Sign in to confirm you’re not a bot”. Pinchflat can then use a browser’s YouTube cookies.

1. Sign in to YouTube with a spare Google account. Never use your main one: YouTube can block an account whose cookies a downloader uses.

2. Export its cookies in the cookies.txt format, with an exporter add-on for your browser.

3. Give them to your lab:

   bromigos lab youtube cookies set ~/Downloads/cookies.txt
   

4. Delete the exported file. Your lab keeps its own copy.

set checks the file and never shows the cookies. It turns on When Needed cookies for every channel and playlist, so Pinchflat only uses them when YouTube asks.

• bromigos lab youtube cookies status says whether there are cookies and how old they are. After about 30 days it reminds you to export fresh ones.
• bromigos lab youtube cookies clear removes them and turns their use off.

Where the cookies go depends on your lab. See Homelab.

Playlists in Jellyfin and Plex

• bromigos lab youtube shows the YouTube downloads card: how many videos are waiting, any that failed, and the newest video from each channel and playlist. The dashboard’s Status tab has the same card. Hover over a row for more.
• bromigos lab youtube sync makes each downloaded YouTube playlist a playlist in Jellyfin or Plex, in the same order as on YouTube. Run it as often as you like: it only changes what’s different. To see what it would do first, add --dry-run.

The Status tab’s Storage card shows each share on your NAS that the lab uses, which NAS it’s on, and how much space is free.

ComfyUI keeps the last job’s models in memory until something frees them. bromigos lab models unload comfyui frees them now. To find the best open models for your graphics cards, see Lab models.

Media requests

Your media walks through requests, tracking, deletion and playback.

If your lab runs a media stack, you can ask it for a film, a show, an anime or music by name. It gets the best quality your lab’s profiles allow, in your languages, and puts it in your media library, where Jellyfin, Plex or your music server plays it. The stack is Seerr, Sonarr for TV, Radarr for films and Lidarr for music.

Find it

bromigos lab media search "cowboy bebop"
bromigos lab media search dune --movie            # or --tv, --anime, --music

Each result has an id, then its year and kind, and the profile it would get. It also says how much disk space it needs, and whether Jellyfin or Plex has it already. A film that isn’t out yet shows its dates, such as “in cinemas 2026-12-18, digital TBA”.

Get it

bromigos lab media get "Cowboy Bebop"
bromigos lab media get tv:tvdb:76885 --specials    # by its id from search

Before it asks for anything, it shows what it will do:

• which profile it picked, and why;
• the audio you’ll get;
• what it fetches now, and whether new episodes come later;
• about how much space it takes, and how much is free.

Then it asks you. Add --yes to skip the question.

If several titles have that name, such as the US and UK versions of a show, it lists them. Then give the id instead.

Which seasons. You choose with --seasons:

A show you already have keeps what it has. bromigos lab media get "Show" --seasons 4 adds season 4 to it. To stop new episodes of a show, run bromigos lab media get "Show" --seasons none --new no.

Films that aren’t out yet. Ask for them now. Your lab watches for the release and fetches the film when it’s out at home, on digital or disc. It never fetches a camera copy from a cinema. bromigos lab media upcoming lists what’s coming and when.

Music. Search with --music, then get an artist (all their albums) or one album. If your lab’s usual sources find nothing for an album, it tries Soulseek next, if your lab has it. It tells you which it used.

YouTube. A YouTube channel’s or playlist’s address goes to Pinchflat, the same as bromigos lab youtube add (above).

Quality

Your lab’s profiles decide the quality, and get takes the best one for each kind:

• Films: a 4K remux or 4K web release when your lab has a 4K profile, else 1080p.
• TV: 4K web releases.
• Anime: the anime profile, usually 1080p Blu-ray, because most anime isn’t made in 4K.
• Music: lossless (FLAC).

--quality 1080p caps it for one request.

Your languages

bromigos lab media language                  # what's set
bromigos lab media language set en ja        # English, with Japanese welcome as a second track
bromigos lab media language anime ja         # anime in Japanese (with subtitles)
bromigos lab media language anime same       # anime like everything else
bromigos lab media language subtitles en     # the subtitles your lab fetches
bromigos lab media language required no      # the first language is only preferred

The first audio language is required. A release without it isn’t downloaded. A release with both tracks, such as an anime with English and Japanese audio, ranks first. Until you set them, your languages follow your desktop’s language. You can also set them in Settings › Lab. --audio ja changes the audio for one request.

Your media library

bromigos media              # or: bromigos lab media

This opens your media library in the terminal. It has a tab for TV, films, music, YouTube, downloads, what’s coming up, Search, and Channels. The top line says how much you have and how much space is free.

Move with the arrow keys or Vim’s (j, k, h, l). Pick a show, an artist or a film, then press a key. Request forms show the plan automatically. Request becomes available when the current preview is ready. Once confirmed, the form shows Requesting… and waits for the result with its controls locked. Errors stay visible in the form.

Add to channel… (c) below the list puts the selected title in a picked channel. Choose the channel’s Add to entry, then Apply channel choice. The selected title’s channel names stay visible beside the button and in the row’s hover hint. A diamond marks a title already in a channel.

Hover over anything to see what it does. The media guide covers Channels, its keys and CLI commands.

Deleting removes the files from the disk, and frees the space. First it shows what goes and how much space that frees. Choose Delete or Cancel; Cancel is selected first. Use Left/Right to choose a button and Enter to activate it. Tab and Shift+Tab also move between controls. Escape or Ctrl+C cancels. Up/Down moves to or from the exclusion checkbox; Enter or Space toggles it. On a season, an episode file or an album, only that goes, and it stops being monitored. You can tick “Don’t fetch it again”, so your lab doesn’t add it back from a list.

The same changes work as commands:

bromigos lab media library tv                     # or movies, music
bromigos lab media monitor "Paper Moon" --season 2 --off
bromigos lab media profile "Paper Moon" WEB-1080p
bromigos lab media delete "Paper Moon" --season 1  # asks you to type the name

What’s happening

bromigos lab media status                    # everything downloading, stuck or requested
bromigos lab media status "Cowboy Bebop"     # one title in detail
bromigos lab media recent                    # what arrived today

status shows each download’s progress and time left. When something is stuck, it says why. For one title, it also shows:

• which seasons are monitored and on disk;
• whether new episodes are picked up;
• the audio languages of the files;
• the subtitles.

If nothing has turned up, it says what your lab’s indexers found when it asked them.

The dashboard’s Requests card shows the same thing. The Calendar panel can show new episodes and film releases too: turn on “Your media server’s releases” in its settings.

VECTOR does all this when you ask him: “download Cowboy Bebop”, “get season 2 of …”, “what’s coming up?”. He tells you what he found and asks before he requests, unless you plainly asked him to download one thing. When it’s in your library, he tells you.

Shortcuts to other commands

• bromigos lab connect is the same as bromigos setup homelab.
• bromigos lab target is the same as bromigos target. See Creating with AI.

If something’s wrong

• “The queue’s service isn’t running.” bromigos lab run tries to start it. If it still isn’t running, run systemctl --user start bromigos-lab.service. To keep it running, run systemctl --user enable --now bromigos-lab.service.
• A job waits for memory. Something else is using the graphics card: another job, or a model someone loaded. The job starts by itself when there’s room. bromigos lab models shows what’s using it.
• A card says “unreachable”. That service didn’t answer. bromigos lab doctor says what to check.

Setting up a lab

bromigos lab provision turns a spare Linux box into your lab. It installs a start page, live graphs, daily backups and monitoring, and connects the lab console to them. Run it with no arguments and it walks you through each step. Each step checks first and asks before it changes anything.

You need:

• a spare box running Debian, Ubuntu, Fedora or Arch Linux, on your network, with SSH on;
• your user account on that box, with its password and the right to use sudo.

bromigos lab provision

What the guided setup asks

1. Tools on this desktop. It checks for Ansible, sops, age, Git and SSH. If some are missing, it shows a sudo pacman -S --needed … command. Run it yourself in another terminal, then press Enter. The setup never runs sudo on your desktop.

2. Your age key. Your lab’s passwords are encrypted with an age key. If you don’t have one, it offers to create one in ~/.config/sops/age/keys.txt. Keep that file safe, and keep a copy in your password manager. Without it, you can’t apply your lab again.

3. The box. It offers to look for the box, the way Find my lab does, and says what it would read. If you type yes, it lists the machines it found that answer SSH. Pick one by number, or choose Type an address. Then give your user name on the box and its SSH port.

4. SSH. The first time, it shows the box’s SSH host key fingerprint. To check it, run ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub at the box’s own screen and keyboard. Type yes only if the two match. Then it offers to run ssh-copy-id, which asks for your password on the box once. If you’re signed in to your Bromigos account, it first offers to add the SSH keys on your account instead. See Your account’s SSH keys on the box.

5. Python and sudo on the box. Provisioning needs Python 3 and sudo without a password on the box. If either is missing, it shows the command or the visudo line to add on the box, and waits for you.

6. The hardware check. It reads the box and lists what it found. It only reads, and never changes a disk. For example:

   GPU: NVIDIA GeForce RTX 3090, 24 GB, driver loaded
   Spare disk: 4 TB HDD, empty, not mounted
   Wired network: enp5s0, 2.5 Gb/s, connected
   USB: Coral Edge TPU. Could be used for fast object detection in Frigate
   

7. What to install. Core is a start page (Homepage), live graphs (Netdata), daily backups (restic), a web server in front (Caddy) and monitoring. Advanced adds Kubernetes, Argo CD and Vault. The setup recommends one for your box. Start with Core if you’re not sure. You can move to Advanced later.

8. Where backups go. It lists other disks and NAS shares already mounted on the box, and the system disk as a last choice. Backups are safest off the system disk. An empty disk can hold backups once you format and mount it on the box yourself. Provisioning never formats or mounts disks.

9. The plan. Choose a folder for your lab’s Git repository, such as ~/lab. The setup writes the plan there and offers to commit it. Then it shows the services, ports, sizes and hardware, and waits for you to type yes.

If you stop at any step, with q or Ctrl+C, run bromigos lab provision again. It skips the steps already done and carries on. To set up a different box instead, run bromigos lab provision --start-over.

Your account’s SSH keys on the box

When this computer is signed in to your Bromigos account, provisioning offers to add the SSH keys on your account to the box. Then any computer with one of those keys can log in to the box, as the user you set it up with.

It lists each key that isn’t on the box yet, with its fingerprint, and adds them only after you type yes:

  You're signed in to your Bromigos account as sam. These SSH keys on it aren't on the box yet:
    SHA256:2pE7Yq0Jm5bYJ8Gk0lO2f2kxq5qkqHq3Lr1QeW7hS1M  ed25519  laptop
  bromigOS can add them to ~/.ssh/authorized_keys for sam on the box, so these keys can log in.
  It only adds lines. The keys already there stay as they are.
  Add this key? Type yes:

• It only adds keys. It never removes or changes a key already on the box.
• If the box doesn’t accept your key yet, adding them asks for your password on the box once. When your own key is one of them, you don’t need ssh-copy-id as well.
• If you say no, it doesn’t ask about those keys for that box again.
• Signed out, it offers nothing. If your account can’t be read, setup carries on without it.

bromigos lab provision --ssh … asks the same question when it runs in a terminal. Add --no-account-keys to skip it. To manage the keys on your account, go to account.bromigos.org › SSH keys.

What you get

Apply starts Caddy, Netdata, restic backups and Homepage, plus Prometheus, Grafana, Loki and Alertmanager. Caddy listens on the box itself at first. Forward it to your desktop, then open http://localhost:8080 in your browser. Netdata is under /netdata/.

ssh -L 8080:127.0.0.1:80 <user>@<host>

After health checks pass, provisioning connects the lab console and runs the doctor. Run bromigos lab to see it, or bromigos lab doctor to check it again. Monitoring is connected automatically. Grafana has starter dashboards for nodes, Kubernetes, GPUs and apps. Its admin password is encrypted with your other credentials. GPU drivers and new storage arrays still need an administrator.

Set it up by hand

The guided setup runs the same commands you can run yourself. Install Ansible, sops and age on your desktop first. The box needs Python 3, an SSH key login and passwordless sudo. Check the SSH host key before you accept it.

ssh-copy-id <user>@<host>
ssh <user>@<host>
age-keygen -o <age-key-file>

Keep the age key file safe. Use the public key printed by age-keygen below. Choose an existing backup destination on the box. A second disk or a mounted NAS share is better than the disk being backed up.

bromigos lab provision --repo <lab-folder> --ssh <user>@<host> \
  --preset core --backup-path <backup-folder> --age-recipient <age-public-key>

The command reads the box and generates your own lab Git repository. It lists services, ports, RAM and disk needs, and the hardware it found. Notes below the list warn about a missing GPU driver or backups on the system disk. Review and commit the files before you apply them.

bromigos lab provision apply --repo <lab-folder>

Apply waits for you to type yes.

To let other machines on your local network reach it, add --listen-address <local-network-address> to the plan. Public addresses are refused. Add --domain <lab-dns-name> to the plan for local HTTPS. Point that name at the box and trust Caddy’s local certificate authority on machines that open it.

Kubernetes, Argo CD and Vault

To add Kubernetes, Helm, Argo CD and Vault, commit the current repository, then generate an Advanced plan. Supply the Git URL where you will publish this repository.

bromigos lab provision --repo <lab-folder> --ssh <user>@<host> \
  --preset advanced --backup-path <backup-folder> --age-recipient <age-public-key> \
  --git-url <your-lab-git-url>

Review, commit and publish the new files at that URL. Then run apply again. Monitoring moves to Kubernetes. The old monitoring containers stop, and their volumes stay for recovery; historical data is not copied into the new volumes. Argo CD keeps its applications in sync with the repository. You can reach its web page with a Kubernetes port forward; its service stays inside the cluster.

Vault shows five recovery shares once, directly in your terminal. Save all five in your password manager before you type stored. Any three can unseal it. You also choose an operator password. Generated service passwords go into Vault. Its initial root token is revoked after setup. Without Vault, passwords are encrypted with sops and age in your lab repository.

Automatic unseal is a separate choice. Type yes only if you want three recovery shares stored in a Kubernetes Secret. Cluster administrators can read them. Keep all five in your password manager even if you choose this option.

An existing cluster

For an existing cluster, install Helm and kubectl on the desktop too. Replace --ssh with --kubeconfig <file> --context <context>. Choose the context explicitly. Vault needs a default storage class. Core needs an existing backup volume claim in lab-core, named by --backup-path. Its web services stay inside the cluster. The plan lists the GPUs that the cluster’s node labels report.

Change the selection

Use --custom for the terminal checklist. The dashboard’s Provision tab has the same service tree and gives you the command for your selection. To change one service:

bromigos lab provision add vault --repo <lab-folder>
bromigos lab provision remove restic --repo <lab-folder>

Commit the repository before changing its plan. These commands only prepare a new plan. Apply still needs your yes. Removing a selection leaves its running service and data in place. Repeating apply preserves backup passwords and Vault’s recovery shares.

Creating a cluster

Prepare a cloud-init template on Proxmox, or a qcow2 cloud image and an existing file-backed pool on a libvirt host. Include Python and the QEMU guest agent. Libvirt also needs its Python bindings, qemu-img and cloud-localds. Local libvirt access must already work; the provisioner never runs desktop sudo.

Allow TCP 6443 from nodes to servers, UDP 8472 between nodes, and TCP 10250 between nodes for metrics. Three-server clusters also need TCP 2379–2380 between the servers. Keep these ports inside your lab network. See the upstream k3s network requirements.

Write a cluster specification. It names the provider, storage pool, bridge or network, VM CPU, RAM, disk, static address, public SSH key, and node role. Choose one or three server nodes and any worker or gpu nodes. GPU images need prepared NVIDIA drivers and the container runtime. The full format and bounded Proxmox token permissions are in the infrastructure reference.

bromigos lab provision cluster --repo <lab-folder> --spec <cluster-json>
bromigos lab provision apply --repo <lab-folder>

The first command reads storage and generates the plan. Enter provider credentials only in its hidden prompt. Review the VM sizes, free space and RAID health, then commit the lab repository. Apply refreshes inventory and waits for yes. It creates only named VMs owned by this plan. It joins the cluster and checks that its nodes are Ready. Three control planes on one hypervisor still share that host’s failure risk.

storage_class chooses Kubernetes volumes. volume_path chooses the local-path folder. nas can name an existing NFS export for other workloads. Monitoring needs local or block storage. No command creates RAID arrays, ZFS pools or NAS shares. Unknown redundancy is shown as a warning.

To grow or shrink the cluster:

bromigos lab provision add-node --repo <lab-folder> --role worker --on <provider>
bromigos lab provision add-node --repo <lab-folder> --role gpu --node-spec <node-json>
bromigos lab provision remove-node <worker-name> --repo <lab-folder>

Adding a node prompts for its resources or reads the node file. It shows the new plan and requires yes before allocating anything. Removal drains the worker first. Workload protection or local pod data can block the drain. Deleting the VM disk needs a second answer naming it. Control-plane removal is refused.

To inspect storage and manage an owned VM:

bromigos lab provision storage list --repo <lab-folder>
bromigos lab provision vm list --repo <lab-folder> --on <provider>
bromigos lab provision vm console --repo <lab-folder> --on <provider> --name <vm-id-or-name>
bromigos lab provision vm snapshot --repo <lab-folder> --on <provider> \
  --name <vm-id-or-name> --snapshot-name <snapshot>

The VM command also accepts start, stop and delete. Changes ask for its ID or name. Shutdown is graceful. Console info returns a link or command. It opens no window. KVM snapshots need a stopped VM. Pool support determines Proxmox snapshot support. For a VM still listed as a cluster node, use remove-node before deletion. The VM command refuses to bypass its drain.

The Provision tab has repository and specification fields, a plan view, node actions, storage inventory and owned VM commands. Commands keep their prompts in your terminal. The capacity card proposes a worker or GPU node after fifteen minutes of pressure or resource-starved pending pods. VECTOR, the desktop AI assistant, can read the same proposal. Neither creates a VM automatically.

Every plan includes monitoring. Kubernetes uses kube-prometheus-stack and Loki. A single box uses Prometheus and node_exporter, Grafana, Loki and Alertmanager. Health probes cover the installed web services. Starter alerts cover node loss, disk space, crashloops, certificate expiry and stale backups. Monitoring stays private. Use SSH forwarding for box endpoints, or Kubernetes port forwarding for cluster services. Grafana listens on port 3001 on a box and port 3000 inside the cluster.

Setting up agents

To set up Hermes Agent or OpenClaw, choose them in the Provision tree or terminal checklist. They use an existing LiteLLM, Ollama or vLLM endpoint. The URL must be reachable from your target and include /v1. For Hermes or OpenClaw on the same Linux box as the model server, use http://lab-model-host:<port>/v1. You need an age public key to encrypt credentials collected during planning. Keep its private identity available for apply.

bromigos lab provision --services hermes openclaw --ssh <user>@<host> \
  --repo <folder> --age-recipient <age-public-key> --llm-url <model-url>

The prompts let you choose a model, profile, memory tools and messaging channels. Enter the model ID served by your endpoint. API keys and bot tokens use hidden prompts. Telegram and Discord are off unless you choose them. Each needs numeric allowed user IDs. Shell and file tools stay disabled.

Review and commit the generated repository, then apply it:

bromigos lab provision apply --repo <folder>

Apply installs containers, keeps their memory and session disks, stores credentials in Vault when present, and checks their health. Without Vault, credentials stay encrypted with sops and age in your repository. The Agents card in bromigos lab shows health, model, gateways and activity metadata. It never shows message text or tokens. Host API ports bind to loopback. Cluster services stay inside the cluster.

NVIDIA NemoClaw has an experimental host plan in the picker. It creates an OpenClaw sandbox on a Linux Docker host through NVIDIA OpenShell. This slice keeps its messaging off and refuses a cluster-only target. It never recreates an existing sandbox. See the agent installer notes for these limits.

In the media library, p opens Play on den TV; P changes the quality profile. Pick a screen, show, season and episode, a movie or a downloaded YouTube video. See Play something on a den screen.

Lab models

bromigOS knows the best open AI models for each job, and which of them fit your homelab’s graphics cards. It can suggest better ones, plan which model goes on which card, and tell you when a better model comes out.

The jobs it knows: chat, coding, memory, pictures, picture edits, cutouts, upscaling, video, 3D, voice, hearing, reading text in pictures, and reading your screen.

You need a connected homelab for most of this. To ask what fits a card you don’t have yet, you don’t.

What fits my graphics cards?

bromigos lab models recommend          # for each card: what runs now, the best fit, upgrades
bromigos lab models pick image 12      # the best picture model for a 12 GB card, and why
bromigos lab models pick llm --gpu "RX 7900 XTX"   # the best chat model for this card
bromigos lab models tiers video        # the best video model at every card size

recommend reads what your lab actually runs and says when something better fits. It also warns when a model you have isn’t licensed where you are, or for the use you chose.

Plan the whole lab

bromigos lab models plan

This gives you up to four ways to set up your lab. Each one says:

• which model goes on which graphics card;
• what stays loaded, and what loads only when it’s needed;
• how full each card gets;
• how fast each job will be;
• what that set-up gives up compared with the others.

You can steer the plan:

bromigos lab models plan --budget "RTX 5070=6G"      # leave room on the card you game on
bromigos lab models plan --goal quality,video=speed  # quality, balanced or speed, per job
bromigos lab models plan --clients 16 --context 32k  # many programs sharing one model

Settings › Lab, under Plan, does the same with sliders and switches, and plans again as you move them.

• Goals. Best quality takes the strongest model that fits, even if it’s slower. Fastest takes smaller models and keeps them loaded. Balanced is in between.
• Speeds. For chat models, speeds come from published tests of the same model on the same card where there are any. Otherwise they’re estimates.
• Licences. Choose any, which is fine for a personal lab, commercial or permissive. Some models aren’t licensed in every country. bromigOS goes by your time zone unless you say where you are.

Upgrades

Nothing changes on your lab unless you ask. In Settings › Lab, under Upgrades, turn on Model upgrades. Then each kind of model can be set to:

For now, bromigOS only tells you about a better model. Applying an upgrade, through your homelab’s own repository, isn’t ready yet.

Once a week, bromigOS fetches the newest list of models. If a better model fits one of your cards, you get one quiet notification. To stop the weekly check:

systemctl --user disable --now bromigos-lab-models.timer

Get the newest list now

bromigos lab models refresh        # the newest signed list
bromigos lab models refresh --hf   # also ask Hugging Face now (needs python-huggingface-hub)

The full tables, with every job, every card size and every licence, are in the developer docs: lab-models.md.

Creating with AI

Some parts of bromigOS use AI:

• VECTOR’s brain, the model he thinks with;
• VECTOR’s voice and hearing;
• the creation tools, which make pictures, picture edits, cutouts, bigger copies of pictures and clips, 3D models and short video loops, for VECTOR and for themes’ artwork.

Each of these can run in one of three places, called targets:

You choose the order. Each job tries the first target, and moves to the next if that one isn’t set up or doesn’t answer.

Keep the cloud out, or let it in

The cloud costs money, so bromigOS is careful with it:

• The cloud only works once you’ve signed in to nolgia, or given a hosted model’s key.
• Putting another target first never adds the cloud.
• bromigOS’s built-in order is homelab, then this machine, then the cloud. The first run normally sets an order without the cloud.
• To be sure the cloud is never used, run bromigos target order homelab local.

VECTOR can’t change this setting, and he never pays for anything on his own. When he makes something, he uses your homelab or this machine. If neither can do it, he says so. He uses nolgia only if you ask for it by name.

See where AI runs now

bromigos target

For each kind of work, this shows what it would use now, and whether that answers. Or open Settings › Creation targets.

Change where AI runs

bromigos target local                 # this machine first
bromigos target homelab               # your homelab first
bromigos target order homelab local   # exactly this order; no cloud
bromigos target local --only llm      # just VECTOR's brain on this machine first
bromigos target reset                 # every kind of work back to the overall order

Or in Settings › Creation targets, choose where each kind of work runs first.

Changes apply at once: to VECTOR’s next reply, and to the next picture you make.

The names for --only are image.generate, image.edit, image.cutout, image.upscale, video.loop, video.upscale, model3d.generate, voice.tts (his voice), voice.stt (his hearing) and llm (his brain).

Set up the creation tools

The first run asked which tools make pictures, picture edits, cutouts, 3D models and video loops. To answer again:

bromigos setup create

The default, “follow where AI runs”, uses the order above. You can instead fix a list of tools for each kind of work. This is also where you sign in to nolgia, if you use it.

Make pictures and holograms

• Ask VECTOR: “make me a picture of…”, “make a hologram of…”.
• Or run a job on your homelab yourself with bromigos lab run. See The lab console.

Your settings files

• ~/.config/bromigos/targets.toml: where AI runs.
• ~/.config/bromigos/create.toml: the creation tools.

The developer docs’ targets.md describes both files.

Extensions

Extensions are add-ons that other people share. An extension can be:

• a theme;
• a hologram deck, or a layer over the background;
• a desktop panel;
• a tool or a skill for VECTOR;
• support for a service in your homelab;
• a bromigos command;
• something to run whenever the theme changes.

Each extension is a git repository. Installing one never changes bromigOS itself, and you can turn it off or remove it at any time.

Find and install an extension

The easiest way is the Extensions window:

1. Open the app launcher (Alt+P) and choose Extensions. Or open the menu and choose INSTALL › Extension catalog….
2. The window lists what you have, then the catalog, with a preview of each.
3. Choose an extension, and choose what to do: install it, update it, see what changed, turn it off or on, or remove it.

Each action opens a terminal that stays open, so you can see what it asks and what it did.

The theme switcher also lists the catalog’s themes after yours. Choosing one installs it and switches to it.

From a terminal

bromigos ext search                  # what the catalog has
bromigos ext search --kind theme     # just the themes
bromigos ext info hello-deck         # what it would install, and what it may do
bromigos ext install hello-deck      # install one from the catalog, by name
bromigos ext install https://github.com/someone/[email protected]   # any repository, at a version

What an extension may do

A theme installs straight away. It’s only colours and pictures.

Anything else shows you its parts, and what it says it needs: the network, files outside its own folder, VECTOR’s tools, or running code. It installs only when you type y. If an update would let it do more, it says NEW PERMISSIONS and asks you again.

After installing, bromigos ext install tells you what to do next. For example:

• a theme: bromigos theme set and its name;
• a deck: bromigos-live plugin and its name;
• a tool for VECTOR: bromigos restart vector.

VECTOR can’t install extensions

VECTOR can list extensions, read about them and search the catalog. He can’t install, update or remove them. The folders they live in are read-only to him.

If a VECTOR tool you installed is changed by hand on disk, his guard notes it in its log. See His terminal and its limits.

Keep extensions up to date

bromigos ext list                    # what's installed, from where, at which version
bromigos ext update --all            # show what changed in each, ask, then update
bromigos ext update thing --check    # just look

An extension installed at a version, such as @v1.0, stays on that version. update tells you about newer versions, and bromigos ext update thing --ref v1.1 moves to one.

Turn off or remove an extension

bromigos ext disable thing           # turn it off, and keep it
bromigos ext enable thing            # turn it back on
bromigos ext remove thing            # remove it

Or in the menu: REMOVE › Extension…. Settings › Extensions also has a switch for each one.

Make your own

bromigos ext new widget my-panel      # a working panel in ./my-panel, to edit
bromigos theme new dusk --from wick   # a theme, starting from the Wick
bromigos ext validate my-panel        # check it
bromigos ext install --copy ./my-panel   # install it from the folder

Every kind of extension has a starter. The kinds are theme, live-deck, live-layer, widget, vector-tool, vector-memory, vector-skill, homelab-adapter, command and hook.

The full guide covers the manifest, permissions, testing an extension without touching your desktop, and publishing it to a catalog. It’s in the developer docs: extensions.md.

Where extensions live

• ~/.local/share/bromigos/ext/: each extension’s files, and the links the desktop reads.
• ~/.local/state/bromigos/ext/ledger.json: a record of what you installed, from where, and what you approved.

Extensions never write to your own ~/.config/bromigos.

Make your own widget

A widget is one of the panels on your desktop. You can make your own in a few minutes: it’s one small Python file inside an extension, which is a folder you can share as a git repository. This page takes you from nothing to a widget other people can install.

You’ll need to know a little Python. The developer docs have the details of every part: plugins.md for what a panel is made of, and widgets.md for sizes and settings.

1. Start from a working widget

bromigos ext new widget my-gauge

This makes a folder, my-gauge, with a widget that already works: it shows the machine’s load average. The folder holds:

• widget.py, the widget itself;
• bromigos-ext.toml, the manifest, which says what the extension is and what it may do;
• README.md, for the people who’ll use it.

2. Make it yours

Open widget.py. The widget is a class with a few parts:

• tick() reads your data. It runs every interval seconds.
• draw(cr, w, h) paints the panel, using the same drawing helpers as bromigOS’s own panels, so it matches every theme.
• region(x, y, w, h, "…") gives each part a hover hint. Every part should have one.

Then tell the gallery about it. These lines are what people see on its card:

    description = "The load average over 1, 5 and 15 minutes"
    category, reads = "system", "the load average"

category is one of system, network, homelab, media, notes or fun. reads says in a few words what data it looks at.

Two more things make a widget feel at home:

• Sizes. A widget can have a compact size, a standard one, and wider or larger ones that show more. You list them in sizes, and draw each its own way. See Size classes.
• Settings. If your widget needs a place, a list of hosts or a sign-in to an online account, list them in settings. bromigOS draws the form for you, and keeps any token in your keyring. See A widget’s settings.

Show real data only. If there’s nothing to read, say so in the panel.

3. Try it

Check the folder the way installing would, then look at the widget without putting it on your desktop:

bromigos ext validate ./my-gauge
bromigos-widgets render ./my-gauge/widget.py out.png                 # draw it to a picture
bromigos-widgets render ./my-gauge/widget.py big.png --size 900x600  # at another size

Open the pictures to see it. Nothing appears on your desktop yet.

When it looks right, install your folder:

bromigos ext install --copy ./my-gauge

A widget runs code, so this shows what it can do and asks you to type yes. Within a few seconds the widget is in the widget gallery: press Super+Alt+W and switch it on. After each change to your folder, run bromigos ext update my-gauge to copy it in again.

4. Share it

Put the folder in a git repository and push it. Tag a version so people can pin it:

git tag v0.1.0 && git push --tags

Anyone can now install it by its link. They open Settings › Widgets, click Install from URL… and paste it, or run:

bromigos ext install https://github.com/you/[email protected]

Before installing, they see your widget’s name, what it reads, its licence and what it may reach.

5. Put it in the catalog

The catalog is the list that Get more widgets shows. To add your widget, open a pull request to bromigos-org/extensions with an entry in its index.toml and a picture of your widget. That repository’s CONTRIBUTING.md has the steps and what reviewers look for.

Updating and rolling back

One command updates everything, and one undoes an update if something goes wrong.

Update bromigOS

1. Open a terminal with Alt+Shift+Enter.

2. Run:

   bromigos update
   

3. Type your password when sudo asks, and answer the package manager’s questions.

Or open the menu and choose UPDATE › Update bromigOS, or choose Update now in Settings › Updates & recovery. Both open a terminal for you.

To see what an update would do first, without changing anything:

bromigos update --check

What an update does

1. It updates every package on the system, bromigOS’s and Arch Linux’s, and then the packages you installed from the AUR. It takes a snapshot just before and just after, so you can undo all of it.
2. It runs any migrations: small changes to your settings that a new version needs. A migration that has to change one of your files keeps a copy of the old one.
3. It applies your theme again.
4. It restarts the parts of the desktop that still run old code: the background, the panels, the bar, notifications, the volume display, VECTOR and his voice. Apps that ask for it, such as BRODEC, get their background services restarted too. Your apps keep running: an app that can restart itself does so when you aren’t using it, and one that might be busy, such as in a call, shows a notification with a Restart now button instead.

When the update asks you to restart

A new Linux kernel or a new NVIDIA graphics driver only runs after the computer restarts. When an update installs one, its last line says so, and a notification says the same:

The graphics driver was updated: restart the computer to use it. Until then, the animated background stays off.

Until you restart, the update leaves alone what needs the graphics card: the animated background and VECTOR. Started now, they couldn’t use the card, and would run slowly on the processor instead. Whatever is already running keeps running. Everything else restarts as usual. Restart the computer when it suits you.

If the animated background starts anyway before then, it shows a still picture instead, and a notification says the graphics card isn’t available (Troubleshooting).

When an update brings a new release, its last line says so. To read what the release brings, run bromigos whats-new, or see What’s new.

Use bromigos update rather than sudo pacman -Syu. A plain pacman -Syu doesn’t run the migrations or the restarts, and bromigos update --rollback can’t undo it. When it changes bromigOS’s packages, pacman reminds you to run bromigos update.

Packages from the AUR

The AUR is where Arch Linux users share recipes for software that Arch Linux doesn’t carry. bromigOS installs paru to build them. bromigos update updates the packages you installed from it too, after everything else.

Anyone can write an AUR recipe, and nobody checks it. So before paru builds a package, it shows you the recipe, or what changed in it, and asks. Read it, or trust whoever maintains it.

• bromigos update --check lists the AUR updates waiting.
• bromigos update --no-aur leaves the AUR out this time.
• bromigos update --yes builds without showing the recipes. Use it only for AUR packages you trust.
• If one fails to build, the update still finishes. It tells you which package failed, and how to try again.
• Without a terminal and without --yes, the update leaves the AUR out, and says so.
• bromigos aur off turns the AUR off: bromigOS removes the paru it installed, and updates leave AUR packages alone. bromigos aur on turns it back on.

Undo an update

If an update broke something:

bromigos update --rollback

It shows what the last update changed, such as the packages and how many files, and asks before it does anything. Then it puts every system file back as it was before the update. This happens on the running system. Afterwards, run bromigos restart, or restart the computer. If the update included a new kernel, restart the computer.

To undo an older update, give its snapshot number. bromigos update --check lists the updates you can undo, with their numbers.

bromigos update --rollback 151

In Settings › Updates & recovery, Roll back… undoes the last update.

If the computer won’t start

Start it from a snapshot in the boot menu. That gives you the system as it was before the update, until you restart. To keep it, run bromigos update --rollback there. In a snapshot, it doesn’t undo an update. It makes the snapshot you started your system, so the next normal start comes up on it.

The system you rolled back from is kept, in case you need something from it. The rollback prints how to delete it once everything works.

What you need for snapshots

Snapshots need the system disk to use the btrfs file system, with snapper set up. An install from the bromigOS USB stick has both. To check your machine:

bromigos rollback status

It says whether your updates are snapshotted, and what can be undone. If something’s missing, it tells you what to run:

• bromigos rollback setup sets up snapper, and adds the snapshots to the boot menu.
• bromigos rollback allow lets you list the system’s snapshots without sudo, so updates can be recorded. It asks for your password once.

Not on btrfs? Updates still work. There’s just no snapshot to go back to, and bromigos update --check says so.

Channels

A channel is the stream of updates you follow.

To see your channel and change it:

bromigos channel                    # which channel you follow
bromigos update --channel edge      # switch to edge, and update

Moving to an older channel, such as from edge back to stable, puts packages that are newer than that channel’s back to its versions. bromigos update --channel does this for you.

You can also change the channel in Settings › Updates & recovery.

The manual

This manual is published next to bromigOS’s packages. It follows the newest code, so on the stable channel it may describe things that haven’t reached you yet. In Settings, F1 opens it on the page you’re looking at.

Hardware

bromigOS looks at your computer when it installs, and sets up what the hardware needs: the graphics driver, and on a laptop the battery, screen brightness, power profiles and the touchpad. This page shows how to check what it found, and how to run that set-up again.

See what bromigOS found

bromigos hw

This lists your graphics cards and their drivers, whether this is a laptop, and what bromigos hw setup would change.

To see which graphics card the login screen and desktop will use at the next login, run:

bromigos hw display

It also says whether you chose that card in Settings, are trying it, or bromigOS chose it. It changes nothing, and it doesn’t report which card an already running desktop is using. bromigos hw graphics lists every card and what it’s for.

Set up your hardware again

Run this if a new graphics card needs its driver set up, or if the hardware check shows missing setup. Updates don’t install drivers on their own.

bromigos hw setup              # asks for your password for the system's part
bromigos hw setup --dry-run    # only say what it would do

It changes only what’s different. It never removes anything, and it never replaces an NVIDIA driver you already have.

It’s also a first-run question (bromigos setup hardware), and an item in the menu: SETUP › Hardware.

Graphics cards

Very old AMD and Intel chips get Mesa without Vulkan.

bromigOS knows a card by its ID, from NVIDIA’s and Mesa’s own lists, rather than guessing from its name.

On a new NVIDIA card the driver loads at the very start, so it is ready for the start-up screen and the login screen.

More than one graphics card

Settings › Graphics lists every graphics card in your computer, whatever its make, and what each one is for. Choose what each card is for explains it. Until you choose, bromigOS decides by itself, as below.

If only one working graphics card has a screen connected, bromigOS prefers that card for the login screen and desktop. You do not need to run setup just to choose it. A card with no screen connected does not take priority because the computer booted on it.

If screens are connected to several cards, or none report a connected screen, bromigOS keeps the existing GPU policy. Your explicit choices still take precedence, including a laptop’s saved preference. Cards bound or reserved for a virtual machine through VFIO, the kernel’s device-assignment interface, are excluded from the automatic choice.

The check happens when the login screen and desktop start. Moving a monitor cable does not move a running desktop’s renderer. Save your work and log out to start a new session; restart the computer if the login screen also needs to choose again.

This chooses among cards whose drivers already work. It does not install a missing driver.

The default bar follows the available screens. If you pinned your bar or monitor settings to a connector name, check those settings after moving the cable. A connector on another card can have a different name.

Choose what each card is for

Open Settings › Graphics. Each card shows its driver and the screens connected to it, and a Use for row with three buttons:

• Desktop: the card that draws the login screen and your desktop. Only a card with a screen connected can be chosen.
• Games and heavy apps: the card games and demanding programs run on, even when the desktop draws on another card. One card can do both.
• Virtual machines: a card kept for virtual machines only, so a VM can use it as its own graphics card. This is called GPU passthrough.

Hover over anything on the page to see what it does. Each use is Automatic until you choose. Automatic for the desktop is the rule above. For games, it’s the strongest card: a card of its own over one built into the processor, then the newest.

If you add, swap or remove a card, bromigOS notices at the next start. A use whose card is gone goes back to Automatic.

Move the desktop to another card

1. Connect a screen to the card.
2. In Settings › Graphics, choose Desktop on that card, then Try it.
3. Enter your password.
4. Log out and log back in. The login screen and the desktop now use that card.
5. Settings opens by itself. Choose Keep.

Until you choose Keep, the old card is still your choice. If the screen stays dark, restart the computer and the old card comes back by itself. You never need the boot menu for this.

You can also go back from a text console. Press Ctrl+Alt+F3, log in, and run:

sudo bromigos hw display reset
sudo systemctl restart display-manager

The first command sets the desktop’s card back to Automatic. The second brings the login screen back. It ends any open session, so restarting the computer works too.

From a terminal, bromigos hw display use CARD chooses a card and bromigos hw display keep keeps it. A card is its PCI address, such as 0000:03:00.0, or its name in /dev/dri, such as card1.

Run games on another card

Choose Games and heavy apps on a card. It’s yours alone, so it needs no password. Programs use it when you start them one of these ways:

• Steam. Turn on Start Steam on the games card. Steam and every game it starts, Proton’s included, then run on that card. It applies when you start Steam from the app launcher, so restart Steam after you turn it on.

• Any other program. Start it with bromigos hw run in front:

  bromigos hw run -- blender
  

• One Steam game. Set its launch options to bromigos hw run -- %command%.

bromigos hw run sets the switches each maker’s driver expects, and nothing when the games card also draws the desktop. bromigos hw run --print shows what it sets.

Keep a card for virtual machines

A card for a virtual machine must pass a few checks first. Open the card’s Virtual machines row in Settings › Graphics to see them. Hover over one to see why it matters. The checks are:

• the IOMMU is on. It’s a firmware setting, and the row says how to turn it on;
• the card doesn’t share its IOMMU group with other devices;
• no screen is connected to it, the desktop doesn’t use it, and another card with a screen stays for the desktop;
• the computer doesn’t start on it. Choose the other card in the firmware settings if it does;
• the start-up files can hold the card. The row says what to add if they can’t.

When they all pass, choose Virtual machines on the card. A terminal opens and asks for your password, then rebuilds the start-up files. Restart the computer. From then on, your virtual machines can use the card, and the desktop and programs can’t.

To give the card back, choose Virtual machines again, or run bromigos hw vfio release CARD, then restart.

bromigOS keeps the card by its PCI address, so it works with two identical cards. The card’s own sound device goes with it. Some older AMD cards need an extra kernel module, vendor-reset, to restart a VM. The checks say when yours does.

NVIDIA’s own driver for an older card

For a GeForce 600 to 10 series card, NVIDIA’s own driver is only in the AUR.

1. Run bromigos hw setup. It asks whether to build the driver with paru. Answer y.
2. paru shows you the recipe to review, then builds the driver.
3. Restart the computer.
4. Run bromigos hw setup again. With the driver loaded, it finishes setting it up.

Until then, the card runs on nouveau. The installer never builds this driver by itself. If you install the driver yourself instead, run bromigos hw setup afterwards too.

Laptops

On a laptop, bromigOS also sets up:

• The battery on the bar. It shows the charge, with + while charging and = when plugged in but not charging. It turns amber below 25% and red below 10%. Hover over it for the time left, the power it’s using and the battery’s health.

• Power profiles: power saver, balanced and performance. The bar shows the profile in use. Click it for the next one. The menu has them under TOGGLE too. If you already run another power manager, such as TLP or tuned, bromigOS leaves it alone.

• The brightness keys, which show the level on screen.

• Two graphics cards. On a laptop with a built-in graphics chip and an NVIDIA or AMD card, the desktop runs on the built-in one to save the battery. The other card sleeps until something needs it. To run a game or a heavy program on the other card, start it with bromigos hw run -- in front, or turn on Start Steam on the games card in Settings › Graphics. Run games on another card has more.

  bromigos hw run -- blender
  

  prime-run (NVIDIA) and DRI_PRIME=1 (AMD) work too.

The touchpad