omnixient/docs/getting-started.md

Getting Started — adopting Omnixient

Omnixient is a Hyprland desktop you build on top of, not a turnkey installer. There are two ways to adopt it:

1. As a flake input (recommended) — your own small repo pins Omnixient as a dependency. You never edit Omnixient's files, so nix flake update omni pulls upstream changes with zero merge conflicts. This is the path below.
2. By forking — clone Omnixient and edit it directly. More control over Omnixient internals, but you maintain a fork. See Forking instead at the end.

This guide assumes a working NixOS install (or the official NixOS ISO). New to NixOS? Read the NixOS manual and the NixOS & Flakes Book first.

---

What's yours vs. what's Omnixient's

In the dependency model your repo is tiny and owns only your stuff:

• flake.nix — pins Omnixient + your settings (identity, hostname, theme…).
• hosts/<host>/default.nix — which packs/options you want.
• hosts/<host>/hardware-configuration.nix — your real hardware scan.

Omnixient (the desktop, theming, packs, modules) comes from the pinned input. You update it like any dependency; it never touches your files.

---

1. Scaffold your config

nix flake init -t git+https://git.atitlan.io/aiolabs/omnixient   # writes flake.nix + hosts/myhost/
cd <your-config>

This drops a starter that already wires omni.lib.mkSystem + omni.nixosModules.omni. Open flake.nix and:

• set omni.url to the real repo (pin a tag for reproducibility, e.g. git+https://git.atitlan.io/aiolabs/omnixient?ref=v1.0.0);
• fill in the settings block:

settings = {
  user = "alice";
  gitName = "Alice Example";
  gitEmail = "alice@example.com";
  hostName = "myhost";
  timeZone = "America/New_York";
  theme = "tokyo-night";        # any module under Omnixient's modules/themes/
  sshKeys = [ ];                # e.g. [ "ssh-ed25519 AAAA… alice@myhost" ]
  stateVersion = "24.11";       # ⚠ the release you FIRST installed — never change
};

stateVersion is the field that bites people: it is not your current NixOS version. It pins stateful defaults from your original install; changing it on a live system can break data.

2. Generate your hardware scan

sudo nixos-generate-config --show-hardware-config \
  > hosts/myhost/hardware-configuration.nix

This captures your disks, filesystems, kernel modules, and CPU microcode. The template ships a placeholder — replace it before building on real hardware.

3. Choose packs and options

Edit hosts/myhost/default.nix. Core (base system + Hyprland desktop + theming) is always on; everything else is opt-in:

omni = {
  enable = true;
  desktop.enable = true;
  user = settings.user;
  theme = settings.theme;

  packs.development.enable = true;   # editors, LSPs, compilers, container CLIs
  packs.media.enable = true;         # gimp, inkscape, mpv, obs, …
  # packs.gaming.enable = true;      # Steam, Lutris, Wine
  # packs.bitcoin.enable = true;     # a real bitcoind + lightning node
};

The full catalog is in docs/packs.md.

4. Track your files, then build

Flakes only see git-tracked files, so stage everything first:

git init && git add .
sudo nixos-rebuild switch --flake .#myhost

Flakes not enabled yet? On a stock NixOS install the first command fails with experimental Nix feature 'nix-command' is disabled — flakes are opt-in. Bootstrap the first build with a one-shot flag:

sudo nixos-rebuild switch --flake .#myhost \
  --extra-experimental-features "nix-command flakes"

Your hosts/myhost/default.nix enables flakes permanently, so later rebuilds don't need the flag.

On the next boot you'll have the Omnixient desktop, plus the bundled helpers (omni-rebuild, omni-update, omni-theme; omni-help lists them).

5. Set your password

The default is initialPassword = "omni". Change it after first login:

passwd

For a declarative password, use hashedPasswordFile with a sops secret (see Secrets).

---

Already on NixOS?

Adopting Omnixient on a machine you already run is the same flow, with three differences — because you're protecting a working system:

1. Enable flakes first (if you're on channels): add nix.settings.experimental-features = [ "nix-command" "flakes" ]; to your current /etc/nixos/configuration.nix and sudo nixos-rebuild switch.
2. Reuse what you have — copy your existing hardware-configuration.nix into hosts/myhost/, and carry your existing stateVersion across verbatim (never bump it).
3. Preview before you switch — Omnixient is a full opinionated desktop (Hyprland + greetd login manager + services), so it will change your desktop:

   sudo nixos-rebuild build   --flake .#myhost   # build only, catch errors
   sudo nixos-rebuild build-vm --flake .#myhost && ./result/bin/run-*-vm  # try it in a VM
   

   When happy, switch. If it's not what you want, roll back instantly from the boot menu or sudo nixos-rebuild switch --rollback — your old generation is untouched.

If you currently run GNOME/KDE/another login manager, expect overlap with greetd + Hyprland; preview in the VM first and disable the old desktop in the same switch.

---

Updating

nix flake update omni            # pull the latest Omnixient
sudo nixos-rebuild switch --flake .#myhost

This can't conflict with your config — Omnixient is a pinned dependency, not a checkout. Roll back by reverting flake.lock; pin a release with omni.url = "git+https://git.atitlan.io/aiolabs/omnixient?ref=v1.0.0".

---

Secrets (optional)

Secrets are off by default — a fresh config builds with zero secret setup. Enable them only if you turn on something that needs one (e.g. an MCP server) or add your own. Omnixient ships the sops-nix module; you supply the data, with your own age key:

# 1. your master key (back this up!)
nix-shell -p age --run 'age-keygen -o ~/.config/sops/age/keys.txt'  # prints age1…

# 2. declare yourself the recipient (copy Omnixient's .sops.yaml.example)
$EDITOR .sops.yaml          # paste your age1… public key

# 3. create + encrypt your secrets (copy secrets/omni.yaml.example)
nix-shell -p sops --run 'sops secrets/omni.yaml'

# 4. TRACK the encrypted file — flakes only see git-tracked files
git add .sops.yaml secrets/omni.yaml

Then enable it in hosts/myhost/default.nix and rebuild:

omni.secrets.enable = true;

modules/secrets.nix reads /home/<user>/.config/sops/age/keys.txt, and only activates when the flag is set and secrets/omni.yaml exists — so it never gets in your way until you ask for it.

---

Building a custom ISO (optional)

From an Omnixient checkout (or nix build git+https://git.atitlan.io/aiolabs/omnixient#omni-iso):

nix build .#omni-iso        # → result/iso/nixos-*.iso

A live Omnixient environment for installing onto new hardware.

---

Forking instead

If you want to modify Omnixient's own modules/themes rather than just consume them, fork the repo and edit in place:

git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni && cd ~/omni

Then model a host on hosts/example/ (copy it to hosts/<yourhost>/, drop in your hardware scan, register it in flake.nix), and edit settings.nix. The trade-off is the usual fork one: to get upstream changes you git pull / rebase and resolve conflicts in any files you've edited. The dependency model above avoids that entirely, which is why it's recommended for most adopters.

---

Where to go next

• docs/packs.md — the pack catalog, enabling/disabling, and reusing packs on a non-Omnixient NixOS.
• docs/ARCHITECTURE.md — how the flake, mkSystem, modules, and theming fit together.
• docs/system-map.md — a file-by-file map of the repo.