How configuration works: defaults and personal overrides

If you want to customize Omarchy but cannot tell which file to edit, start with one small goal: add a shortcut to open the file manager, then change that same shortcut to open network settings. The exercise connects config loading, key matching, application launch, and diagnosis.

Examples are checked against pinned source, not run in your session. Open Setup → Keybindings and confirm it uses ~/.config/hypr/bindings.lua. Older .conf installations need their own syntax; do not mix in Lua.

1. How the three file layers cooperate

Layer	Location in this source	Responsibility
Omarchy-managed defaults	/usr/share/omarchy/default/hypr/	Desktop behavior updated with the package
Personal entry point	~/.config/hypr/hyprland.lua	Initialization and loading defaults plus personal files
Personal files by responsibility	~/.config/hypr/bindings.lua and others	Your changes, without directly editing packaged files

A simplified loading sequence:

hyprland.lua
  → bootstrap.lua: prepare the Omarchy configuration environment
  → default.hypr.omarchy: load default behavior
  → hypr.monitors / input / bindings / looknfeel / autostart
  → default.hypr.toggles: apply dynamic toggles
  → remaining personal configuration in the entry file

This is a sequence diagram, not lines to paste into your config again. Entry point source

Personal config follows defaults so it can override them. However, ordinary options, added bindings, window rules, and toggles do not all mean “the last line wins.” Adding another key action does not automatically remove an earlier one.

2. Choose the responsibility before the file

Goal	First place to inspect
Add or replace shortcuts	bindings.lua
Change monitor placement or scale	monitors.lua; see the dual-display guide
Adjust keyboard layout, mouse, or touchpad	input.lua
Adjust gaps, borders, or animations	looknfeel.lua
Start additional apps at login	autostart.lua
Change bar widgets, lock, or idle timings	~/.config/omarchy/shell.json
Change terminal-specific settings	~/.config/foot/foot.ini

The bar, terminal, and compositor all appear on the desktop, but their settings do not all belong in Hyprland files. Official file responsibilities

3. Prepare: working commands, an unused key, and an original copy

Check that the commands exist:

command -v nautilus
command -v nmtui

Expect executable paths. With no output, establish what is installed before binding a missing program. Launch the file manager from the desktop and run nmtui in the terminal. It should show network settings; exit without changing connections.

List current shortcuts:

omarchy menu keybindings --print

This exercise uses Super + Ctrl + N as a teaching choice, not a guaranteed unused key. Check the list and your personal configuration. If occupied, choose another combination and update every example consistently.

Save the original file:

cp -i ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-first-edit

If an older backup already exists, decide whether it is still your only original before overwriting. Use new backup names for later important changes. This protects one file; see backup boundaries for a full plan.

4. First change: add a key action

Open your personal file through Setup → Keybindings and add below existing valid configuration:

o.bind("SUPER + CTRL + N", "Open file manager", { launch = "nautilus" })

Part	Meaning
o.bind	Omarchy’s helper for adding a binding
First string	Key combination, matching your plan
Second string	Description shown in the shortcut list
{ launch = "nautilus" }	An application action processed by Omarchy’s launch helper

This is not a universal Lua API; it depends on Omarchy initialization. Do not paste it into unrelated Lua programs. Helper implementation

Save and exit. In default Neovim, press Esc, type :wq, and press Enter. :q! discards unsaved changes. The documented menu edit workflow handles the relevant reload or process restart when the editor exits.

Expected: the list contains Open file manager, the shortcut opens it, and its existing shortcut still works. Checking an adjacent action catches accidental edits to other lines.

5. Second change: replace the same shortcut

Replace the line you added with:

o.rebind("SUPER + CTRL + N", "Open network settings", { tui = "nmtui" })

Do not retain both lines and treat another o.bind as replacement. o.rebind unbinds the combination before adding its replacement. The tui helper launches a terminal interface inside a terminal, rather than treating it as a graphical application.

Intent	Method
Add an unused combination	o.bind(...)
Replace an existing combination	o.rebind(...)
Remove without replacement	hl.unbind("SUPER + CTRL + N")

Save and exit again. Expected: the same key opens nmtui, not the file manager. Exit without changing networking. To return to the previous step, use a file-manager o.rebind or restore the original copy.

6. Diagnose the stage that failed

Observation	First check	Stage narrowed down
Edits disappear after exiting	Saved changes and correct path	File writing
Desktop reports a config error	Named file and line; brackets, quotes, commas	Parsing
New description absent from list	Entry point loads the file; reload succeeded	Loading
Action listed, key does nothing	Combination, keyboard layout, competing bindings	Key matching
Program errors or immediately exits	Run the same program in a terminal	Application launch
Fails after another login	Entry point, duplicate config, session conditions	Persistence and loading order

Change one cause at a time. A listed description does not prove the app launches; a working terminal command does not prove the key matches. Those checks cover different stages.

When directly editing files, do not assume all applications reread settings automatically. Follow the component’s reload, new-window, or restart instructions. This exercise uses the menu to reuse Omarchy’s edit workflow.

7. Undo and maintain across updates

Restore the original file after the exercise if desired:

cp -i ~/.config/hypr/bindings.lua.before-first-edit ~/.config/hypr/bindings.lua

Confirm you intend to replace the present configuration. Reopen it through the same menu, inspect it, then save and exit to use the same loading workflow. Check the exercise key returned to its previous state and familiar keys still work.

Separating overrides from packaged files lets defaults keep improving. It does not guarantee personal config never needs maintenance: updates can change options and helpers. Record the reason, file, version baseline, and expected action; check those custom behaviors after updates. One broken shortcut does not justify resetting everything.

Disabling whole groups of default shortcuts requires flags set before defaults load. That has wider effects and is outside this exercise. Binding template guidance

Continue with a specific customization

Once the loading model is clear, choose personal shortcuts, bar layout, fonts and text size, window rules, configuration maintenance, or application theme differences. Each follows a concrete task through verification and rollback.

For a complete working setup, continue with the next six task guides:

Your goal	Guide
Balance usable space, focus cues and motion	Window appearance comparisons
Stop shrinking every window when more apps open	Choose a window layout
Explain why one launch still uses the old app	Defaults and Web Apps
Keep tasks accessible when docking and undocking	Plan workspaces across displays
Start apps without competing startup owners	Autostart and background tasks
Present or run a long task, then restore normal locking	Lock, screensaver and stay awake

Sources and scope

Reviewed on 2026-10-12: official dotfiles, pinned entry point, binding template, and helpers. The exercise is source-based teaching; key availability and launch behavior need verification in your own session.