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 Omnixient is a Hyprland desktop you build on top of, not a turnkey installer.
turnkey distro installer. Adopting it means **forking it and making it There are **two ways to adopt it**:
yours**. Almost everything you need to change is funnelled through one
file (`settings.nix`) plus your machine's hardware scan.
This guide assumes you already have a working NixOS install (or are 1. **As a flake input (recommended)** — your own small repo pins Omnixient as
installing from the official NixOS ISO). If you don't know NixOS at all, a dependency. You never edit Omnixient's files, so `nix flake update omni`
read [the NixOS manual](https://nixos.org/manual/nixos/stable/) and pulls upstream changes with zero merge conflicts. This is the path below.
[NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/) first. 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 This guide assumes a working NixOS install (or the official NixOS ISO). New
> actual machine — a Framework Desktop with WireGuard, the aiolabs dev to NixOS? Read the [NixOS manual](https://nixos.org/manual/nixos/stable/)
> environment, and a Bitcoin/Lightning workflow. You'll want your own and the [NixOS & Flakes Book](https://nixos-and-flakes.thiscute.world/)
> host directory rather than inheriting all of that. See first.
> [Step 4](#4-make-it-your-host).
--- ---
## 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 In the dependency model your repo is tiny and owns only **your** stuff:
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.
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 ```bash
git clone https://git.atitlan.io/aiolabs/omnixient.git ~/omni nix flake init -t github:<your-org>/omnixient # writes flake.nix + hosts/myhost/
cd ~/omni cd <your-config>
``` ```
You can put it anywhere; `/etc/nixos` and `~/omni` both work. Rebuild This drops a starter that already wires `omni.lib.mkSystem` +
commands below use `--flake .#<host>` from inside the clone. `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 ## 2. Generate your hardware scan
```bash ```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 This captures your disks, filesystems, kernel modules, and CPU microcode.
microcode). You'll place it into your host directory in step 4. The template ships a placeholder — replace it before building on real
hardware.
> A stray `hardware-configuration.nix` at the repo root is gitignored on ## 3. Choose packs and options
> purpose — the tracked copy belongs in your host directory.
## 3. Fill in `settings.nix` Edit `hosts/myhost/default.nix`. Core (base system + Hyprland desktop +
theming) is always on; everything else is opt-in:
Open `settings.nix` and set every field for your machine:
```nix ```nix
{ omni = {
user = "alice"; # your Linux username enable = true;
gitName = "Alice Example"; desktop.enable = true;
gitEmail = "alice@example.com"; user = settings.user;
hostName = "nimbus"; # your machine's hostname theme = settings.theme;
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
}
```
The comments in the file explain each field. The **`stateVersion`** packs.development.enable = true; # editors, LSPs, compilers, container CLIs
warning is the one that bites people: it is *not* your current NixOS packs.media.enable = true; # gimp, inkscape, mpv, obs, …
version — it pins stateful defaults from your original install, and # packs.gaming.enable = true; # Steam, Lutris, Wine
changing it on a live system can break data. # packs.bitcoin.enable = true; # a real bitcoind + lightning node
## 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
];
}
];
}; };
``` ```
If your username differs from the template's, also create The full catalog is in **[docs/packs.md](packs.md)**.
`users/<youruser>/home-manager.nix` — copy `users/user/home-manager.nix`,
a one-line shim to the shared `home.nix`.
**What's maintainer-specific in `hosts/omni/` — leave it out of yours:** ## 4. Track your files, then build
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.
> Prefer the absolute-minimum change? You *can* skip renaming: replace Flakes only see **git-tracked** files, so stage everything first:
> `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
```bash ```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 > **Flakes not enabled yet?** On a stock NixOS install the first command
> turned on flakes, this first command fails with something like > fails with `experimental Nix feature 'nix-command' is disabled` — flakes
> `experimental Nix feature 'nix-command' is disabled` — flakes are > are opt-in. Bootstrap the first build with a one-shot flag:
> opt-in on stock NixOS. Bootstrap the first build with a one-shot flag:
> >
> ```bash > ```bash
> sudo nixos-rebuild switch --flake .#<host> \ > sudo nixos-rebuild switch --flake .#myhost \
> --extra-experimental-features "nix-command flakes" > --extra-experimental-features "nix-command flakes"
> ``` > ```
> >
> You only need this **once** — Omnixient's own config enables > Your `hosts/myhost/default.nix` enables flakes permanently, so later
> `nix-command` and `flakes` (`configuration.nix`), so every later > rebuilds don't need the flag.
> `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.)
On the next boot you'll have the Omnixient desktop. After that, the bundled On the next boot you'll have the Omnixient desktop, plus the bundled helpers
helpers take over (`omni-rebuild`, `omni-update`, `omni-theme`, (`omni-rebuild`, `omni-update`, `omni-theme`; `omni-help` lists them).
`omni-help` lists them all — note they're individual `omni-*`
commands, not a single dispatcher).
## 7. Set your password ## 5. Set your password
The template ships `initialPassword = "omni"` (`modules/users.nix`). The default is `initialPassword = "omni"`. Change it after first login:
Change it immediately after first login:
```bash ```bash
passwd passwd
``` ```
For a permanent declarative password, switch to For a declarative password, use `hashedPasswordFile` with a sops secret
`hashedPasswordFile` with a sops-managed secret (see (see [Secrets](#secrets-optional)).
`modules/secrets.nix` and `.sops.yaml`).
---
## 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) ## Building a custom ISO (optional)
From an Omnixient checkout (or `nix build github:<your-org>/omnixient#omni-iso`):
```bash ```bash
nix build .#omni-iso # → result/iso/nixos-*.iso 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 ## Where to go next
- **[docs/packs.md](packs.md)** — the pack catalog, enabling/disabling, and - **[docs/packs.md](packs.md)** — the pack catalog, enabling/disabling, and
reusing packs on a non-Omnixient NixOS. 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. modules, and theming fit together.
- **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo. - **[docs/system-map.md](system-map.md)** — a file-by-file map of the repo.