The omfreebdy Manual

This is your guide to omfreebdy, a complete desktop environment built on FreeBSD. It gives you a tiling window manager, a curated set of tools, a theme system that touches everything from your terminal to your RGB LEDs, and a collection of scripts that handle the fiddly bits of desktop life — WiFi, audio, screenshots, power management — so you can focus on your work.

omfreebdy ships two desktop profiles: Wayland (Hyprland) and X11 (i3). They share the same theme system, the same scripts, and the same CLI tools. The only difference is the window manager and its supporting stack. Wayland is the default and recommended for most hardware. X11 is there for older GPUs or proprietary NVIDIA drivers.

This manual is organized as a journey. Start at the top if you just installed. Skip to any section if you know what you are looking for.

The Basics

Everything in omfreebdy happens via the keyboard. The mouse works — you can drag windows, click waybar, resize with Super+mouse — but the keyboard is faster for everything.

The Super key (the Windows key, the Command key, whatever your keyboard calls it) is your modifier. Every keybinding in omfreebdy starts with Super plus something. If you forget a binding, press Super+F1 to see them all.

Your first three bindings:

Keys	Action
`Super+Return`	Open a terminal
`Super+Space`	Open the app launcher
`Super+W`	Close the current window

That is enough to get started.

First Boot

On your first login, omfreebdy-setup runs automatically. It walks you through WiFi connection, timezone detection, picking your first theme, setting your git identity, and installing Hyprland plugins. If you ever want to re-run it:

omfreebdy-setup --force

You will land on a desktop with a status bar at the top (Waybar on Wayland, i3status on X11) and a wallpaper. Open a terminal with Super+Return and you are home.

omfreebdy uses a tiling layout by default. New windows split the current space automatically. You do not need to think about placement — just open things and they tile.

Moving focus between windows uses arrow keys or vim-style hjkl:

Keys	Action
`Super+H` / `Super+Left`	Focus left
`Super+L` / `Super+Right`	Focus right
`Super+K` / `Super+Up`	Focus up
`Super+Down`	Focus down
`Alt+Tab`	Cycle through windows

Moving windows uses the same keys with Shift added: Super+Shift+H swaps the focused window left, Super+Shift+L swaps it right, and so on.

Resizing uses Super+minus to shrink and Super+equal to grow. For directional resizing, add Ctrl to the arrow keys: Super+Ctrl+Left shrinks horizontally, Super+Ctrl+Right grows horizontally.

Workspaces give you ten virtual desktops. Switch with Super+1 through Super+0. Move a window to another workspace with Super+Shift+1 through Super+Shift+0. Navigate sequentially with Super+Tab (next) and Super+Shift+Tab (previous).

A few more layout tricks:

Keys	Action
`Super+F`	Toggle fullscreen
`Super+T`	Toggle floating
`Super+O`	Pop out window (float + pin on top)
`Super+J`	Toggle split direction
`Super+S`	Toggle scratchpad
`Super+G`	Group windows into tabs

Themes

omfreebdy ships 18 themes: catppuccin, catppuccin-latte, ethereal, everforest, flexoki-light, gruvbox, hackerman, high-contrast, kanagawa, matte-black, miasma, nord, osaka-jade, ristretto, rose-pine, tokyo-night, vantablack, and white.

Press Super+Shift+T to open the theme picker. Select a theme and everything changes: terminal colors, status bar, window borders, lock screen, wallpaper, Neovim colors, and if you have RGB hardware, your LEDs too. The change is instant.

From the command line:

theme-set catppuccin      # Set a specific theme
theme-set --list          # List all themes
theme-set --select        # Open the picker
theme-current             # Show current theme

Each theme is defined by a colors.toml file with 16 terminal colors plus accent, background, foreground, cursor, and selection colors. Themes can also include wallpaper images in a backgrounds/ directory.

Hotkeys

This is not the complete list — press Super+F1 for that. These are the ones you will use every day.

Launching

Keys	Action
`Super+Return`	Terminal (Ghostty)
`Super+Shift+Return`	Browser (Brave)
`Super+Space`	App launcher (Fuzzel)
`Super+E`	File manager (Nautilus)
`Super+Ctrl+T`	System monitor (btop)
`Super+Ctrl+B`	Bluetooth manager
`Super+Ctrl+W`	WiFi manager
`Super+Ctrl+A`	Audio controls

Windows

Keys	Action
`Super+W`	Close window
`Super+F`	Fullscreen
`Super+T`	Toggle floating
`Super+Backspace`	Toggle transparency
`Super+Shift+C`	Center floating window
`Super+Ctrl+P`	Toggle layout mode (dwindle/master/scrolling)
`Super+Ctrl+Shift+S`	Toggle square aspect

System

Keys	Action
`Super+Escape`	System menu (logout/reboot/shutdown)
`Super+Ctrl+L`	Lock screen
`Super+Shift+T`	Theme picker
`Super+B`	Next wallpaper
`Super+N`	Dismiss notification
`Super+Shift+N`	Toggle do-not-disturb
`Super+Ctrl+N`	Toggle nightlight
`Super+Ctrl+S`	Create ZFS snapshot
`Super+]`	Zoom in
`Super+[`	Zoom out
`Super+Shift+]`	Reset zoom
`Super+F1`	Show all keybindings

Clipboard

Keys	Action
`Super+C`	Copy (works everywhere, including terminals)
`Super+V`	Paste
`Super+X`	Cut
`Super+Ctrl+V`	Clipboard history

Quick Text

Keys	Action
`Super+Ctrl+1`	Type your name
`Super+Ctrl+2`	Type your email
`Super+Ctrl+Shift+-`	Type em-dash (—)

Snippets are configured in ~/.config/omfreebdy/quick-type.conf. Add your own key=value pairs and invoke them with quick-type <key>.

Media

Volume, brightness, and media playback keys work as expected on your keyboard. Hold Alt with volume keys for 1% precision adjustments.

Terminal

Ghostty is the default terminal. It launches with Super+Return, runs at 90% opacity, and picks up your theme colors automatically when you switch themes.

Ghostty is fast, GPU-accelerated, and supports ligatures out of the box. The default font is JetBrainsMono Nerd Font. If you prefer a different terminal, Foot is also installed as a lightweight backup.

Configuration lives at ~/.config/ghostty/config. The theme-managed parts are generated by theme-set — edit non-color settings there freely.

Browser

Brave runs via the FreeBSD linuxulator (Linux binary compatibility layer). It is a Chromium-based browser with built-in ad blocking. Launch it with Super+Shift+Return.

You can install web apps (PWAs) with webapp-install and remove them with webapp-remove. Web apps get their own launcher entries and behave like native applications.

App Launcher

Press Super+Space to open the app launcher. On Wayland this is Fuzzel — a fast, minimal launcher that searches installed applications and PATH commands. On X11 it is Rofi, which does the same thing with a different look.

Start typing to filter. Enter to launch. That is it.

The emoji picker is at Super+Ctrl+E. The clipboard history manager is at Super+Ctrl+V.

Notifications

Mako handles notifications on Wayland. Notifications appear in the top-right corner and auto-dismiss after a few seconds.

Keys	Action
`Super+N`	Dismiss current notification
`Super+,`	Dismiss current notification (alternative)
`Super+Shift+,`	Dismiss all notifications
`Super+Shift+N`	Toggle do-not-disturb
`Super+Alt+,`	Invoke (click) last notification

Configuration: ~/.config/mako/config.

File Manager

Nautilus is the graphical file manager. Open it with Super+E or Super+Shift+F. It handles drag-and-drop, thumbnails, and network shares.

For terminal-based file browsing, eza replaces ls with colored output and git status indicators. zoxide remembers your frequently-visited directories — type z projects instead of cd ~/Projects/work/projects.

Neovim

Neovim ships with a LazyVim configuration. It picks up your current theme automatically. Open files with nvim in the terminal.

The config lives at ~/.config/nvim/. LazyVim provides LSP support, fuzzy finding, git integration, and a file tree out of the box. If you have your own Neovim config, just replace the directory.

tmux

tmux uses Ctrl+Space as the prefix (not the default Ctrl+b). This is more comfortable and avoids conflicts with Neovim.

Sessions persist after you close the terminal. Use tmux attach to reconnect to your last session. The status bar is themed to match your current omfreebdy theme.

Tmux Layouts

omfreebdy includes preset layout scripts for common workflows:

tdl — dev layout (editor + terminal panes)
tdlm — dev layout with monitoring
tsl — server layout

Configuration: ~/.config/tmux/tmux.conf.

Shell Tools

Your shell comes loaded with modern replacements for classic Unix tools:

Tool	Replaces	What it does
`eza`	`ls`	File listing with colors, icons, git status
`bat`	`cat`	Syntax-highlighted file viewing
`zoxide`	`cd`	Smart directory jumping (`z` command)
`fzf`	—	Fuzzy finder for everything
`ripgrep`	`grep`	Fast code search (`rg` command)
`fd`	`find`	Fast file finder
`dust`	`du`	Disk usage visualizer
`btop`	`top`	Beautiful system monitor
`lazygit`	—	Terminal UI for git
`starship`	—	Themed prompt with git info
`fastfetch`	`neofetch`	System info display
`tldr`	`man`	Simplified command help

These are all available in your PATH immediately.

System Monitor

Press Super+Ctrl+T to open btop in a terminal. It shows CPU, memory, disk, and network usage with a themed interface.

For a quick system overview, run fastfetch in any terminal. For disk usage, dust gives you a visual breakdown.

AI and LLM

omfreebdy includes llama-server with Vulkan GPU acceleration for local LLM inference. It provides an OpenAI-compatible API on port 8080.

service llama-server start     # Start the server
curl http://localhost:8080/health  # Check status

Models are stored in /usr/local/share/llama/models/ in GGUF format. Download GGUF files from HuggingFace with fetch. Configure the service via sysrc llama_server_* variables in /etc/rc.conf.

hermes-agent runs in a Linux jail and connects to your local llama-server for conversational AI. Launch it with the hermes wrapper script.

omfreebdy-ai-skill is a desktop assistant that uses your local llama-server to answer questions about omfreebdy and suggest commands. Run it from the terminal or via Help > AI Skill in the system menu.

AI Coding Tools

Install coding agents via the system menu (Install > AI Tools) or directly:

Tool	Install	What it does
Claude Code	`npm install -g @anthropic-ai/claude-code`	Anthropic’s CLI coding agent
OpenCode	`go install github.com/opencode-ai/opencode@latest`	Open-source coding agent
Pi	`npm install -g @mariozechner/pi-coding-agent`	Extensible terminal coding agent harness

These work with multiple AI providers and alongside the local LLM stack.

Music

spotify-player is a terminal-based Spotify client. It requires a Spotify Premium account. Launch it from the terminal or bind it to a key. It picks up your theme colors automatically.

Media keys (play, pause, next, previous) work with spotify-player and any other MPRIS-compatible player.

Screen Recording

Keys	Action
`Super+R`	Toggle screen recording
`Super+Shift+R`	Record a selected area

Recordings use wf-recorder (Wayland) and are saved to your home directory. The capture menu at Super+Ctrl+C gives you more options. Recordings now include audio via OSS. If gpu-screen-recorder is installed, it is preferred for better performance.

Screenshots

Keys	Action
`PrtSc`	Select an area to capture
`Shift+PrtSc`	Capture entire screen
`Ctrl+PrtSc`	Capture current window
`Super+Shift+S`	Screenshot to clipboard
`Super+PrtSc`	Color picker

Area screenshots open in Satty for annotation before saving. Screenshots are saved to ~/Pictures/ by default. Use screenshot smart to pick a window by title from a menu and capture its exact geometry.

Voice Dictation

Hold Super+Z to record your voice, release to transcribe. This uses Voxtype, which runs Whisper locally with Vulkan acceleration. Install it first with voxtype-install.

WiFi

The WiFi indicator in Waybar is clickable — it opens the WiFi manager. You can also press Super+Ctrl+W or run:

wifi-manager select    # Interactive network picker
wifi-manager scan      # Scan for networks
wifi-manager status    # Show current connection

WiFi power saving can be toggled with wifi-powersave for better battery life on laptops.

Bluetooth

Press Super+Ctrl+B to open bluetui, a terminal-based Bluetooth manager. Pair devices, connect, disconnect — all from the keyboard. The Waybar bluetooth module shows connection status at a glance.

Audio

FreeBSD uses OSS as its native audio layer. PipeWire and WirePlumber run on top to provide compatibility with Linux audio APIs (PulseAudio, ALSA) that many desktop apps expect.

Volume keys on your keyboard work out of the box with on-screen display feedback via SwayOSD. To switch between audio outputs (speakers, headphones, HDMI):

audio-switch     # Interactive output picker
audio-setup status  # Show current audio config

Configuration: PipeWire and WirePlumber handle routing automatically. The underlying OSS devices are managed by the kernel. Most users never need to touch audio config.

Power Management

The battery indicator in Waybar shows charge level and estimated remaining time. Click it or run:

power-profile              # Show current profile
power-profile performance  # Maximum performance
power-profile balanced     # Default
power-profile powersave    # Battery saving

battery-status gives you detailed battery info. battery-monitor runs in the background and warns you at low levels. hibernate suspends to disk when available.

Display

Brightness keys on your keyboard adjust screen brightness with on-screen display feedback. Keyboard backlight keys work too, if your hardware supports them.

For nightlight (warm screen at night), press Super+Ctrl+N to toggle hyprsunset.

Monitor scaling can be cycled with Super+Ctrl+M. For multi-monitor setup, edit ~/.config/hypr/conf/monitors.conf.

USB Drives

USB drives are mounted automatically via devd. Supported filesystems include exFAT, NTFS, and ext2/3/4. The usb-mount script handles manual mount/unmount:

usb-mount         # List and mount available drives
usb-mount unmount  # Safely unmount

MTP devices (phones, cameras) work via jmtpfs.

Printing

CUPS handles printing. Most USB and network printers are detected automatically.

printer-setup web    # Open CUPS admin in browser (localhost:631)
printer-setup status # Show printer status

Drivers for HP (hplip) and many other printers (gutenprint) are pre-installed.

Firewall

PF (Packet Filter) is enabled by default with a sane policy: allow outbound, deny inbound except established connections.

firewall status    # Show current rules
firewall allow 22  # Allow SSH inbound
firewall deny 22   # Remove SSH rule

Edit /etc/pf.conf directly for advanced configuration.

VPN

WireGuard and Tailscale are supported via the vpn-setup helper. See the VPN guide for full setup instructions.

vpn-setup status                # Show all VPN status
vpn-setup tailscale install     # Install and enable Tailscale
vpn-setup wireguard install     # Install WireGuard kernel module

Boot Environments

omfreebdy runs on ZFS, which means you can snapshot your entire system before risky changes and roll back if something breaks.

boot-env create         # Snapshot current system
boot-env list           # List all snapshots
boot-env activate <name>  # Boot into a snapshot

Press Super+Ctrl+S to create a quick snapshot from anywhere. This is your safety net before system updates or config experiments.

Configuration

Everything lives in ~/.config/. omfreebdy installs sensible defaults, but every config file is yours to edit:

Directory	What it controls
`~/.config/hypr/`	Hyprland (window manager, bindings, monitors)
`~/.config/waybar/`	Status bar
`~/.config/ghostty/`	Terminal
`~/.config/foot/`	Foot terminal (backup)
`~/.config/mako/`	Notifications
`~/.config/fuzzel/`	App launcher
`~/.config/nvim/`	Neovim
`~/.config/btop/`	System monitor
`~/.config/tmux/`	tmux
`~/.config/omfreebdy/`	Theme state and settings

When you run omfreebdy-update, your configs are not overwritten. New defaults are only applied if the file does not already exist.

Creating Themes

A theme is a directory under ~/.omfreebdy/themes/<name>/ containing a colors.toml file and optionally a backgrounds/ directory with wallpaper images.

The colors.toml format:

accent = "#89b4fa"
cursor = "#f5e0dc"
foreground = "#cdd6f4"
background = "#1e1e2e"
selection_foreground = "#1e1e2e"
selection_background = "#f5e0dc"

color0 = "#45475a"
color1 = "#f38ba8"
color2 = "#a6e3a1"
# ... color3 through color15

The 16 colors follow the standard terminal color scheme (color0-7 are normal, color8-15 are bright). accent is used for window borders, UI highlights, and status bar accents.

After creating your theme, run theme-set <name> to apply it.

Fonts

JetBrainsMono Nerd Font is the default. Nerd Fonts include programming ligatures and thousands of icons used by starship, eza, and Neovim.

font-set             # Interactive font picker
font-list            # List installed fonts
font-current         # Show current font

Noto and Noto Emoji are installed for international text and emoji rendering.

Wallpapers

Press Super+B to cycle through wallpapers in your current theme’s backgrounds/ directory. Add your own images (PNG, JPG, WEBP) to ~/.omfreebdy/themes/<current-theme>/backgrounds/ and they will be included in the rotation.

Keybinding Customization

Edit ~/.config/hypr/conf/bindings.conf to change or add keybindings. The format is:

bindd = MODIFIERS, KEY, Description, action, arguments

After saving, Hyprland picks up changes automatically — no restart needed.

i3 (X11 Mode)

If you chose the X11 profile, you get i3 instead of Hyprland. The keybindings are the same (Super as mod key, same shortcuts for workspaces, windows, and launching). The differences:

Launcher: Rofi instead of Fuzzel
Compositor: picom for transparency and shadows
Screenshots: scrot instead of grim/slurp
Clipboard: xclip instead of wl-clipboard
Lock screen: i3lock instead of hyprlock
Status bar: i3status instead of Waybar

Configuration: ~/.config/i3/config and ~/.config/picom/picom.conf.

RGB LEDs

If you have OpenRGB-compatible hardware (keyboards, mice, motherboard lighting), themes sync your LEDs automatically:

rgb-control          # Manual RGB control

The accent color from your current theme is used for LED colors. OpenRGB communicates directly with hardware via the operator group — no sudo required.

Locale and Input

locale-set            # Pick your locale and keyboard layout
input-method-setup    # Set up CJK or other input methods
tz-auto               # Auto-detect timezone
tz-select             # Manual timezone picker

Updates

omfreebdy-update    # Pull latest configs + upgrade packages + run migrations

This does three things: git pull for the latest omfreebdy code, pkg upgrade for system packages, and omfreebdy-migrate for any config migrations needed between versions.

Update Channels

omfreebdy-channel stable   # Stable releases (default)
omfreebdy-channel dev      # Development branch

The dev channel tracks the latest changes. Stable waits for tested releases.

Autologin

Use autologin-toggle to enable or disable automatic login on boot. When enabled, the display manager skips the password prompt and logs you straight into your desktop session.

Accessibility

omfreebdy includes several accessibility features:

Desktop zoom: Press Super+] to zoom in, Super+[ to zoom out, and Super+Shift+] to reset zoom. Useful for presentations or low-vision use.
Keyboard accessibility: The accessibility-keys script configures sticky keys (press modifiers sequentially instead of holding), slow keys (ignore brief key presses), and bounce keys (ignore repeated key presses).
High-contrast theme: The high-contrast theme provides maximum foreground/background contrast for readability.
Screen reader: Orca is available in the extras package set. Install it with pkg install orca for speech and braille output.

Troubleshooting

When something is not working:

omfreebdy-debug        # Run diagnostics and show system state
omfreebdy-log-upload   # Upload logs for support
system-info            # Detailed hardware and software info

Common issues:

Black screen after login: Your GPU may not support Wayland. Try the X11 profile: log out, select i3 from the display manager.
No sound: Run audio-setup status to check your audio config. PipeWire and WirePlumber should be running. Check cat /dev/sndstat for detected devices.
WiFi not connecting: Run wifi-manager scan to see available networks. Some WiFi chipsets need firmware — check dmesg | grep -i wifi.
Theme not applying fully: Run theme-refresh to force a full re-application of the current theme.
Keybindings not working: Press Super+F1 to verify bindings are loaded. Check ~/.config/hypr/conf/bindings.conf for syntax errors.

Security

omfreebdy takes a few opinionated security stances:

sudo for privilege escalation. Both sudo and doas are installed; scripts use sudo by default.
PF firewall enabled by default. Outbound allowed, inbound denied except established connections.
ZFS boot environments let you roll back after any change.
Disk health monitoring via disk-health watches your drives with SMART.
Full disk encryption is supported during FreeBSD installation (not managed by omfreebdy, but recommended).

FAQ

Can I use omfreebdy on an existing FreeBSD install? Yes. Clone the repo and run mise run setup. It installs packages and copies configs but does not modify your base system.

Do I need both Wayland and X11? No. Pick one during setup. Most people should use Wayland (Hyprland). Use X11 only if your GPU does not support Wayland.

How do I install more software? Use pkg install <package> for FreeBSD packages. For Linux applications, Brave already runs via the linuxulator. The sandbox script provides isolated environments for additional Linux apps.

Can I use a different terminal? Yes. Change $terminal in ~/.config/hypr/conf/bindings.conf to any terminal emulator. Foot is pre-installed as an alternative.

How do I add my own keybindings? Edit ~/.config/hypr/conf/bindings.conf. Changes are picked up immediately.

Where are screenshots saved? ~/Pictures/ by default.

How do I switch back to the default theme? Run theme-set catppuccin.

What is the display manager? Ly, a minimal TUI login manager. It runs on the console and lets you pick between Hyprland and i3 sessions.