aiolabs/omnixient
9
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

docs(getting-started): rewrite for the dependency model

Browse source 
Lead with consuming OmniXY as a flake input (omnixy.lib.mkSystem +
nixosModules.omnixy via `nix flake init -t`): tiny consumer repo,
conflict-free `nix flake update omnixy`. Add an 'Already on NixOS?'
section (reuse hardware scan + stateVersion, preview in VM, rollback),
a Secrets opt-in walkthrough, and keep forking as a documented
alternative.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Padreug 2026-06-28 10:51:12 +02:00
commit a054bfaa38
1 changed files with 175 additions and 133 deletions
Download patch file Download diff file Expand all files Collapse all files

316
docs/getting-started.md
View file

@ -1,201 +1,243 @@
# Getting Started — adopting Omnixient on your machine
# Getting Started — adopting Omnixient
Omnixient is a personal NixOS config published as a starting point, not a
turnkey distro installer. Adopting it means **forking it and making it
yours**. Almost everything you need to change is funnelled through one
file (`settings.nix`) plus your machine's hardware scan.
Omnixient is a Hyprland desktop you build on top of, not a turnkey installer.
There are **two ways to adopt it**:
This guide assumes you already have a working NixOS install (or are
installing from the official NixOS ISO). If you don't know NixOS at all,
read [the NixOS manual](https://nixos.org/manual/nixos/stable/) and
[NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/) first.
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](#forking-instead) at the end.
> **Heads-up:** the `omni` host (`hosts/omni/`) is the maintainer's
> actual machine — a Framework Desktop with WireGuard, the aiolabs dev
> environment, and a Bitcoin/Lightning workflow. You'll want your own
> host directory rather than inheriting all of that. See
> [Step 4](#4-make-it-your-host).
This guide assumes a working NixOS install (or the official NixOS ISO). New
to NixOS? Read the [NixOS manual](https://nixos.org/manual/nixos/stable/)
and the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/)
first.
---
## The two things that are truly yours
## What's yours vs. what's Omnixient's
1. **`settings.nix`** — identity, hostname, timezone, theme, SSH keys, and
the all-important `stateVersion`. One file, fully commented.
2. **`hosts/<yourhost>/hardware-configuration.nix`** — the scan of your
actual hardware. Generated by `nixos-generate-config`; never copy
someone else's.
In the dependency model your repo is tiny and owns only **your** stuff:
Everything else (the desktop, theming, packs) is shared and opt-in.
- `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. Get the repo
## 1. Scaffold your config
```bash
git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni
cd ~/omni
nix flake init -t github:<your-org>/omnixient # writes flake.nix + hosts/myhost/
cd <your-config>
```
You can put it anywhere; `/etc/nixos` and `~/omni` both work. Rebuild
commands below use `--flake .#<host>` from inside the clone.
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.
`github:<your-org>/omnixient/v1.0.0`);
- fill in the `settings` block:
```nix
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
```bash
sudo nixos-generate-config --show-hardware-config > /tmp/hardware-configuration.nix
sudo nixos-generate-config --show-hardware-config \
> hosts/myhost/hardware-configuration.nix
```
Review it (it captures your disks, filesystems, kernel modules, CPU
microcode). You'll place it into your host directory in step 4.
This captures your disks, filesystems, kernel modules, and CPU microcode.
The template ships a placeholder — replace it before building on real
hardware.
> A stray `hardware-configuration.nix` at the repo root is gitignored on
> purpose — the tracked copy belongs in your host directory.
## 3. Choose packs and options
## 3. Fill in `settings.nix`
Open `settings.nix` and set every field for your machine:
Edit `hosts/myhost/default.nix`. Core (base system + Hyprland desktop +
theming) is always on; everything else is opt-in:
```nix
{
user = "alice"; # your Linux username
gitName = "Alice Example";
gitEmail = "alice@example.com";
hostName = "nimbus"; # your machine's hostname
timeZone = "America/New_York";
theme = "tokyo-night"; # any of modules/themes/*.nix
sshKeys = [
"ssh-ed25519 AAAAC3Nza... alice@nimbus"
];
stateVersion = "24.05"; # ⚠ the release you FIRST installed — never change later
}
```
omni = {
enable = true;
desktop.enable = true;
user = settings.user;
theme = settings.theme;
The comments in the file explain each field. The **`stateVersion`**
warning is the one that bites people: it is *not* your current NixOS
version — it pins stateful defaults from your original install, and
changing it on a live system can break data.
## 4. Make it your host
The cleanest path is your own host directory, and there's a ready-made
template to copy — **`hosts/example/`** (a minimal, generic host, kept
build-checked in `flake.nix` so it never rots):
```bash
cp -r hosts/example hosts/nimbus # name it your host
cp /tmp/hardware-configuration.nix \
hosts/nimbus/hardware-configuration.nix # your real scan (step 2)
```
`hosts/example/default.nix` imports your hardware scan + the shared Omnixient
base and enables a sensible starter set of packs — edit it to taste (it's
fully commented). Then register the host in `flake.nix` (copy the
`example` block, rename it):
```nix
# flake.nix → nixosConfigurations
nimbus = mkSystem "nimbus" {
inherit system;
user = settings.user; # add `devEnv = true;` if you want the dev-env
extraSpecialArgs = { inherit settings; };
extraHmArgs = { inherit settings; };
modules = [
{ home-manager.sharedModules = [
inputs.nix-colors.homeManagerModules.default
inputs.lazyvim.homeManagerModules.default
inputs.walker.homeManagerModules.default
];
}
];
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
};
```
If your username differs from the template's, also create
`users/<youruser>/home-manager.nix` — copy `users/user/home-manager.nix`,
a one-line shim to the shared `home.nix`.
The full catalog is in **[docs/packs.md](packs.md)**.
**What's maintainer-specific in `hosts/omni/` — leave it out of yours:**
the `framework-desktop-*` hardware module, `wireguard.nix` (a private
tunnel), `omni.packs.aiolabs.enable` and the whole `dev-env { … }` block
(the aiolabs Lightning workflow), and the Framework `fwupd`/polkit rule.
## 4. Track your files, then build
> Prefer the absolute-minimum change? You *can* skip renaming: replace
> `hosts/omni/hardware-configuration.nix` with your scan, strip the
> maintainer-specific lines from `hosts/omni/default.nix`, set
> `settings.hostName`, and build `.#omni`. The flake attribute name and
> your machine's hostname are independent. A dedicated host dir is just
> tidier once you have more than one machine.
## 5. Choose your packs
Core (base system + Hyprland desktop + theming) is always on. Everything
else is opt-in via `omni.packs.<name>.enable`. The full catalog and the
standalone-import story are in **[docs/packs.md](packs.md)**.
```nix
omni.packs.media.enable = true; # gimp, inkscape, mpv, obs, …
omni.packs.development.enable = true; # editors, LSPs, compilers, container CLIs
omni.packs.gaming.enable = true; # Steam, Lutris, Wine
# omni.packs.bitcoin.enable = true; # a real bitcoind + lightning node (opt-in import)
```
## 6. Build and switch
Flakes only see **git-tracked** files, so stage everything first:
```bash
sudo nixos-rebuild switch --flake .#<host>
git init && git add .
sudo nixos-rebuild switch --flake .#myhost
```
> **Flakes not enabled yet?** If your existing NixOS install hasn't
> turned on flakes, this first command fails with something like
> `experimental Nix feature 'nix-command' is disabled` — flakes are
> opt-in on stock NixOS. Bootstrap the first build with a one-shot flag:
> **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:
>
> ```bash
> sudo nixos-rebuild switch --flake .#<host> \
> sudo nixos-rebuild switch --flake .#myhost \
> --extra-experimental-features "nix-command flakes"
> ```
>
> You only need this **once** — Omnixient's own config enables
> `nix-command` and `flakes` (`configuration.nix`), so every later
> `nixos-rebuild` / `omni-rebuild` works without the flag.
> (Alternatively, add
> `nix.settings.experimental-features = [ "nix-command" "flakes" ];`
> to your *current* `/etc/nixos/configuration.nix`, run
> `sudo nixos-rebuild switch`, then come back to this step.)
> 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. After that, the bundled
helpers take over (`omni-rebuild`, `omni-update`, `omni-theme`,
`omni-help` lists them all — note they're individual `omni-*`
commands, not a single dispatcher).
On the next boot you'll have the Omnixient desktop, plus the bundled helpers
(`omni-rebuild`, `omni-update`, `omni-theme`; `omni-help` lists them).
## 7. Set your password
## 5. Set your password
The template ships `initialPassword = "omni"` (`modules/users.nix`).
Change it immediately after first login:
The default is `initialPassword = "omni"`. Change it after first login:
```bash
passwd
```
For a permanent declarative password, switch to
`hashedPasswordFile` with a sops-managed secret (see
`modules/secrets.nix` and `.sops.yaml`).
For a declarative password, use `hashedPasswordFile` with a sops secret
(see [Secrets](#secrets-optional)).
---
## 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:
```bash
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
```bash
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 = "github:<your-org>/omnixient/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:
```bash
# 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:
```nix
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 github:<your-org>/omnixient#omni-iso`):
```bash
nix build .#omni-iso # → result/iso/nixos-*.iso
```
The ISO is a live Omnixient environment for installing onto new hardware.
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:
```bash
git clone https://github.com/<your-org>/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](packs.md)** — the pack catalog, enabling/disabling, and
reusing packs on a non-Omnixient NixOS.
- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — how the flake, `mksystem`,
- **[docs/ARCHITECTURE.md](ARCHITECTURE.md)** — how the flake, `mkSystem`,
modules, and theming fit together.
- **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo.