Omnixient NixOS

Transform your NixOS installation into a fully-configured, beautiful, and modern development system based on Hyprland. Omnixient brings the elegance of declarative configuration to desktop Linux, creating a reproducible and version-controlled development environment.

🌀 aiolabs/omnixient

This repository is derived from TheArctesian/omnixy and evolves independently at git.atitlan.io/aiolabs/omnixient. It keeps the desktop layer that OmniXY ships (Hyprland, themes, ISO builder, dev shells) and adds infrastructure for managing a multi-project Bitcoin/Lightning development workflow on top of it.

We're not actively syncing changes from TheArctesian/omnixy — the diff has grown large enough that the two projects serve different audiences now. If you only want the polished desktop, the original is the right place. If you want the dev environment, fleet deploy story, and aiolabs-specific tooling, this is.

What this fork adds:

• modules/dev-env/ — declarative module for managing bare repos, worktrees, navigation helpers, tmux sessions, regtest docker env, upstream-PR workflow, and shared git hooks. Replaces an imperative bash installer. See modules/dev-env/README.md for design notes.
• lib/mksystem.nix — uniform host constructor (mitchellh-style) so flake.nix defines hosts as mkSystem "name" { user = ...; devEnv = true; }; instead of repeating nixpkgs.lib.nixosSystem calls.
• lib/overlays.nix — pin select fast-moving packages (claude-code, gh, direnv) to nixpkgs-unstable while keeping the rest on the primary channel.
• modules/cache.nix — substituters + trusted public keys for shared binary caches.
• Makefile — single-command wrappers for switch, test, build, update, cache, check, clean, fmt, shellcheck.
• hosts/<name>/ and users/<user>/ directory layout — per-host and per-user split following the mitchellh/nixos-config pattern. Each host file consumes currentSystemName and currentSystemUser via specialArgs from mksystem.
• server-deploy flake input — a separate forgejo flake at aiolabs/server-deploy is the source of truth for which refs ship to which production host. dev-env walks its flake.lock to auto-derive default project entries.
• Smoke-test flake checks — nix flake check builds three lightweight derivations that exercise the dev-env option schema end-to-end without needing a full system rebuild.

Documentation:

• modules/dev-env/README.md — dev-env module design and option reference
• INTEGRATION_NOTES.md — verification + rollback notes from the integration
• Issue tracker — open follow-ups

Quick aiolabs-specific workflow:

make switch HOST=omni           # nixos-rebuild switch via mkSystem
dev-env-bootstrap --dry-run       # preview the worktree tree
dev-env-bootstrap                 # materialize bare repos + worktrees
lb dev                            # cd ~/dev/lnbits/dev
bs                                # cd ~/dev/bitspire/bitspire/dev
prb lnbits fix-bug                # create upstream PR worktree
dev-deploy host5                   # deploy via locked server-deploy input
dev-deploy --local host1          # deploy with local worktree overrides

🧭 Philosophy & ethos

Omnixient is a personal config published as a starting point, not a distro you install and forget. A few principles shape it:

• One config, every host, via a host factory. lib/mksystem.nix builds each machine from the same function; new machines are a small host directory, not a fork of the whole tree.
• Core + opt-in packs. A small always-on core (base system, Hyprland desktop, theming) plus self-gating omni.packs.<name>.enable bundles. Install the core, switch on the goodies you want — and reuse the packs on a non-Omnixient NixOS via flake.nixosModules. See docs/packs.md.
• Adopt = fork. Everything machine- or person-specific is funnelled through settings.nix + your hardware scan, so making it yours is a couple of edits, not an archaeology dig. See docs/getting-started.md.
• No framework until it earns its place. Plain flake outputs and the module system, deliberately not flake-parts / auto-import — those get adopted only when a real need (a second CPU architecture, publishing packs widely) appears. See Design lineage.
• Declarative all the way down, with escape hatches. Reproducible by default; modules = [ … ] on a host stays available for the one-off that doesn't fit a pack.

✨ Features

• 🎨 Beautiful Themes: Ships with 11 carefully crafted themes (Tokyo Night, Catppuccin, Gruvbox, Nord, and more) - all declaratively configured
• 🚀 Modern Stack: Pure Wayland with Hyprland compositor, Waybar, Ghostty, Alacritty, Neovim with LazyVim, Walker launcher (with Elephant backend), Wiremix audio, Satty screenshots
• 📦 Declarative Everything: Entire system configuration as code - reproducible across machines
• 🛠️ Development Ready: Pre-configured environments for Rust, Go, Python, Node.js, C/C++, and more via Nix shells
• 🔄 Atomic Updates: Rollback capability, no broken states, system-wide updates with one command
• 🎯 Modular Design: Feature flags for Docker, gaming, multimedia - enable only what you need
• ⚡ Flake-based: Modern Nix flakes for dependency management and reproducible builds
• 🏠 Home Manager: User environment managed declaratively alongside system configuration
• 💿 ISO Builder: Build custom live ISOs with your configuration

📋 Requirements

• NixOS unstable (flake tracks nixos-unstable)
• 8GB RAM minimum (16GB+ recommended for development)
• 40GB disk space (for Nix store and development tools)
• UEFI system (for systemd-boot configuration)

🚀 Installation

Adopting this on your own machine? Read docs/getting-started.md — it walks the full adoption checklist: edit settings.nix (identity, hostname, theme, SSH keys, stateVersion), generate your hardware scan into your host directory, pick your packs, and rebuild. Omnixient is a personal config published as a starting point, so adopting = forking and making it yours.

Direct Flake Installation (Recommended)

On an existing NixOS system:

git clone https://git.atitlan.io/aiolabs/omnixient.git
cd omni
# 1. edit settings.nix   2. put your hardware scan in hosts/<host>/
# (see docs/getting-started.md), then:
sudo nixos-rebuild switch --flake .#omni

(If you want the original TheArctesian/omnixy desktop without the aiolabs additions, that lives separately at github.com/TheArctesian/omnixy and has its own install instructions.)

After install, the aiolabs Makefile shortcuts the daily commands:

make switch HOST=omni   # rebuild + switch
make test HOST=omni     # nixos-rebuild test
make build HOST=omni    # build the toplevel without switching
make check                # nix flake check (smoke tests + flake lint)
make update               # nix flake update
make cache                # push the host's closure to $CACHE
make fmt                  # nixfmt every .nix file
make shellcheck           # shellcheck every .sh file

Building a Custom ISO

Build a live ISO with the Omnixient configuration:

# Clone the repository
git clone forgejo@git.atitlan.io:aiolabs/omnixient.git
cd omni

# Build the ISO (this will take time on first build)
nix build .#iso

# The ISO will be available at:
ls -la result/iso/

Write the ISO to a USB drive:

sudo dd if=result/iso/nixos-*.iso of=/dev/sdX bs=4M status=progress

🎮 Usage

System Management

All system commands are individual omni-* executables (there is no bare omni dispatcher). Tab-complete omni-<Tab> to see the full set, or run omni-help.

omni-help              # Show all available commands
omni-update            # Update system and flake inputs
omni-clean             # Clean and optimize Nix store
omni-info              # Show system information (alias: omni-status)
omni-rebuild           # Rebuild system configuration
omni-search <package>  # Search for packages

Theme Management

omni-theme             # List available themes
omni-theme tokyo-night # Switch to Tokyo Night theme
omni-theme-picker      # Interactive theme picker

# Available themes:
# - tokyo-night (default)
# - catppuccin
# - catppuccin-latte
# - gruvbox
# - nord
# - everforest
# - rose-pine
# - kanagawa
# - matte-black
# - osaka-jade
# - ristretto

Development Environments

# Enter development shells
nix develop               # Default development shell
nix develop .#rust        # Rust development environment
nix develop .#python      # Python development environment
nix develop .#node        # Node.js development environment
nix develop .#go          # Go development environment
nix develop .#c           # C/C++ development environment

Package Management

omni-search firefox    # Search for packages
nix search nixpkgs python # Alternative package search

# Install packages by editing configuration
# Add to modules/packages.nix, then:
omni-rebuild           # Apply changes

⌨️ Key Bindings

Key Combination	Action
Super + Return	Open terminal (Ghostty)
Super + B	Open browser (Firefox)
Super + E	Open file manager
Super + D	Application launcher (Walker)
Super + Q	Close window
Super + F	Fullscreen
Super + Space	Toggle floating
Super + 1-9	Switch workspace
Super + Shift + 1-9	Move window to workspace
Print	Screenshot region (annotate with satty)
Shift + Print	Screenshot full screen (annotate with satty)
Super + Print	Screenshot region to clipboard
Super + L	Lock screen

Feature-gated autostart

When you enable optional features in configuration.nix, apps launch on dedicated workspaces at login:

Feature	Workspace	Apps
(always)	1	Terminal with tmux, default browser
media	4	Spotify
communication	5	Signal, Element, Ferdium

📁 Project Structure

omni/
├── flake.nix                       # flake inputs + nixosConfigurations via mkSystem
├── flake.lock
├── Makefile                        # aiolabs: switch/test/build/cache/check workflows
├── configuration.nix               # main NixOS config (imported by hosts/omni via shim)
├── home.nix                        # home-manager user config (imported via users shim)
├── hardware-configuration.nix      # hardware-specific (generated)
├── settings.nix                    # single source of truth for user/host/git identity
├── iso.nix                         # ISO image variant (built directly, not via mkSystem)
├── INTEGRATION_NOTES.md            # aiolabs: dev-env integration verification + rollback
│
├── lib/                            # aiolabs: flake-level helpers
│   ├── mksystem.nix                #   uniform host constructor
│   └── overlays.nix                #   nixpkgs-unstable pinning for fast-moving pkgs
│
├── hosts/                          # aiolabs: per-host config files
│   └── omni/
│       └── default.nix             #   shim → ../../configuration.nix + dev-env settings
│
├── users/                          # aiolabs: per-user split (mitchellh-style)
│   └── user/
│       └── home-manager.nix        #   shim → ../../home.nix
│
├── modules/                        # NixOS module collection
│   ├── core.nix                    # core Omnixient options + presets
│   ├── lib.nix                     # omni.lib helpers (makeScript, paths, etc.)
│   ├── packages.nix                # categorized package collections
│   ├── development.nix             # language toolchains
│   ├── services.nix                # system services
│   ├── users.nix                   # user account management
│   ├── boot.nix                    # boot config
│   ├── security.nix                # security settings
│   ├── scripts.nix                 # Omnixient utility scripts
│   ├── menus.nix                   # application launchers
│   ├── walker.nix                  # walker launcher (uses upstream flake module)
│   ├── fastfetch.nix               # system info display
│   ├── colors.nix                  # color scheme plumbing
│   ├── mcp.nix                     # MCP server integrations
│   ├── cache.nix                   # aiolabs: substituters + trusted-public-keys
│   ├── desktop/
│   │   └── hyprland.nix            # Hyprland compositor
│   ├── themes/                     # declarative theme system (11 themes)
│   ├── hardware/                   # GPU/audio/bluetooth/touchpad
│   └── dev-env/                    # aiolabs: multi-project dev environment
│       ├── default.nix             #   imports options + lib + config
│       ├── options.nix             #   schema (projects, forgejo, deploy, regtest, tmux)
│       ├── lib.nix                 #   mkProject, deriveFromFlakeInput helpers
│       ├── config.nix              #   wires everything together
│       ├── README.md               #   design notes + extension guide
│       ├── presets/
│       │   └── aiolabs.nix         #   the aiolabs project list + tmux layouts
│       ├── scripts/                #   ported + new bash helpers
│       │   ├── bootstrap.sh        #     dev-env-bootstrap (idempotent materializer)
│       │   ├── nav.sh              #     lb / wa / bs / lam / ext / shared / repos / prs
│       │   ├── worktree.sh         #     wt / wts / wtu + lnbits sync/rebase
│       │   ├── pr-helpers.sh       #     prb / prc / prl
│       │   ├── rebase.sh           #     fork-onto-upstream rebase helper
│       │   ├── regtest.sh          #     regtest-start/stop/status
│       │   ├── status.sh           #     dev-status
│       │   ├── tmux-launch.sh      #     dev-tm
│       │   ├── deploy.sh           #     dev-deploy [--local]
│       │   └── git-hooks/
│       │       └── pre-commit      #     shared via core.hooksPath
│       ├── docs/                   #   shipped runbooks
│       │   ├── upstream-prs.md
│       │   └── secrets-management.md
│       └── tests/
│           └── smoke.nix           #   minimal nixosSystem for `nix flake check`
│
└── packages/                       # custom packages
    ├── scripts.nix                 # Omnixient utility scripts as nix packages
    └── plymouth-theme.nix          # plymouth boot theme

Anything marked aiolabs is added by this fork. Everything else is upstream.

🖥️ Hardware notes

AMD Strix Halo (Ryzen AI Max 300) + MT7925 wifi/bluetooth: the bluetooth side of the MT7925 runs over an internal USB bus that can get stuck after a warm reboot — the adapter appears but firmware upload times out. A full power off (cold boot) always recovers it. The mt7925-bt-heal systemd service handles the rfkill unblock + power-on once firmware loads successfully. Do not run rfkill unblock bluetooth manually when the adapter is in a broken state (MAC 00:00:00:00:00:00) — it kills the device.

🏗️ Architecture

Flake-based Configuration

• Pinned Dependencies: All inputs locked for reproducibility
• Multiple Outputs: NixOS configs, development shells, packages, apps, and ISO
• Home Manager Integration: User environment managed alongside system

Modular Design

• Feature Flags: Enable/disable Docker, gaming, development tools, etc.
• Theme System: Complete application theming through Nix modules
• Hardware Support: Automatic detection and configuration
• Development Environments: Language-specific shells with all dependencies

Pure Wayland

• No X11 Dependencies: Full Wayland compositor stack
• Hyprland: Dynamic tiling compositor with animations
• Native Wayland Apps: Ghostty, Alacritty, Firefox with Wayland support

🎨 Themes

Omnixient includes beautiful themes that configure your entire desktop environment:

• Tokyo Night (default) - Clean, dark theme inspired by Tokyo's night lights
• Catppuccin - Soothing pastel theme (Mocha variant)
• Catppuccin Latte - Light variant of Catppuccin
• Gruvbox - Retro groove color scheme
• Nord - Arctic, north-bluish color palette
• Everforest - Comfortable green color scheme
• Rose Pine - Natural pine and rose colors
• Kanagawa - Inspired by Japanese paintings
• Matte Black - Pure black minimalist theme
• Osaka Jade - Jade green accents
• Ristretto - Coffee-inspired brown theme

Each theme declaratively configures:

• Terminal colors (Ghostty, Alacritty, Kitty)
• Editor themes (Neovim, VS Code)
• Desktop environment (Hyprland, Waybar, Mako)
• Applications (Firefox, BTtop, Lazygit)
• GTK/Qt theming

🔧 Customization

Adding System Packages

Edit modules/packages.nix and add packages to the appropriate category, then rebuild:

omni-rebuild

Adding User Packages

Edit home.nix for user-specific packages and rebuild.

Creating Custom Themes

1. Copy an existing theme as a template:

cp modules/themes/tokyo-night.nix modules/themes/my-theme.nix

2. Edit the color palette and application configurations
3. Add to flake.nix theme list
4. Rebuild to apply

Testing Changes

# Test configuration without switching
nixos-rebuild build --flake .#omni

# Test in virtual machine
nixos-rebuild build-vm --flake .#omni
./result/bin/run-omni-vm

# Check flake evaluation
nix flake check

# Format Nix code
nixfmt *.nix modules/*.nix     # or: make fmt

🚀 Building ISOs

Build custom live ISOs with your configuration:

# Build ISO
nix build .#iso

# ISO location
ls result/iso/nixos-*.iso

The ISO includes:

• Full Omnixient desktop environment
• Auto-login live session
• Hyprland with selected theme
• Development tools
• Installation utilities

🤝 Contributing

Issues + PRs at git.atitlan.io/aiolabs/omnixient/issues.

This repo evolves independently of TheArctesian/omnixy — we don't sync changes upstream and you don't need to send the same fix to two places. If you want to contribute to the original OmniXY desktop project instead, head to github.com/TheArctesian/omnixy directly; the two are now separate projects sharing common ancestry.

For aiolabs/omnixient contributions, the dev-env module ships an upstream-PR helper for sending PRs to OUR upstream OSS dependencies (lnbits, lamassu, nix-bitcoin, etc.) — see modules/dev-env/docs/upstream-prs.md.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TheArctesian/omnixy — the original OmniXY project this is derived from. Desktop, themes, ISO, hyprland config all originate there. We've evolved independently since.
• Inspired by Omakub and Omarchy by DHH — the original opinionated desktop setups
• The dev-env mksystem pattern is adapted from mitchellh/nixos-config — see lib/mksystem.nix
• The dev-env cross-level option forwarding pattern is inspired by henrysipp/omarchy-nix, another NixOS port of omarchy
• Built on NixOS - the declarative Linux distribution
• Using Hyprland compositor - dynamic tiling Wayland compositor
• Home Manager - declarative user environment
• Theme configurations adapted from community themes and color schemes
• Nix Flakes - for reproducible and composable configurations

Design lineage

Omnixient's structure is a deliberate synthesis of patterns from several widely-respected NixOS configs. (This is a well-sourced summary — the load-bearing facts were checked against upstream, but treat the per-author characterizations as summary, not gospel.)

• mitchellh/nixos-config (Mitchell Hashimoto) — the origin of our lib/mksystem.nix host-factory pattern: one function builds every host, derives per-host/per-user paths, picks nixosSystem, wires home-manager. Its known limitation — the flat modules = [ … ] ++ optionals … list only scales by if-appending and exposes nothing for reuse — is exactly what the packs model addresses.
• Misterio77/nix-starter-configs (Gabriel Fontes, also author of nix-colors, which Omnixient imports) — the canonical "expose reusable modules as flake outputs" (nixosModules = import ./modules/…) pattern. This is where our flake.nixosModules.<pack> reuse comes from.
• hlissner/dotfiles (Henrik Lissner, Doom Emacs) — the enable-gate feature DSL: options under a <name>.enable namespace, each module always imported but inert until enabled (mkIf cfg.enable). This is the template for our omni.packs.<name>.enable toggles. (We take the enable-gate idea and leave the heavier CLI-wrapper machinery he himself disclaims.)
• flake-parts / import-tree / haumea / disko — surveyed and deliberately deferred. flake-parts' perSystem pays off with multiple architectures; auto-import (import-tree/haumea) breaks selective per-host imports unless every module is enable-gated; disko is install-time-only. We revisit these when a second architecture or wide pack publishing makes them earn their place.
• henrysipp/omarchy-nix — inspiration for the dev-env cross-level option-forwarding pattern.

🔗 Links

• NixOS Manual - Official NixOS documentation
• Home Manager Manual - User environment management
• Hyprland Wiki - Hyprland configuration reference
• Nix Package Search - Search available packages
• aiolabs/omnixient issues — issues + PRs for this repo
• TheArctesian/omnixy — the original OmniXY project (separate, no longer tracked for syncing)

📚 Learning Resources

• Nix Pills - Deep dive into Nix
• NixOS & Flakes Book - Modern NixOS guide
• Zero to Nix - Gentle introduction to Nix

---

Built with ❤️ using the power of NixOS and declarative configuration