Customize a desktop

A desktop ships a whole opinion, already wired. So customising it isn't assembly: it's turning a handful of dials, and every one of them lives in the same file.

The one file you edit

There are two halves to a haus machine, and they never mix:

• haus (github:hausfold/haus): the layer. Generic, no identity, upstream. You never edit it to use it.
• Your config (~/.config/nix): a small flake that imports haus, plus one host file, hosts/<hostname>/default.nix, where you live.

Everything on this page goes in that host file:

haus edit       # opens it in $EDITOR
haus rebuild    # builds first; a broken config never activates

It's a plain nix-darwin module, so whatever you write merges with what haus already declares. Because it's a separate repo, haus update pulls a newer layer without touching your identity, your apps or your overrides.

Finding the knob

Three ways in, and none of them is reading a reference end to end:

• Your own config already lists them. A fresh install drops a hosts/<host>/options.nix beside your host file: every haus.* option at its default, one sentence each, all commented out. Uncomment what you want. haus options regenerates it from the build you're actually running, so it can't advertise something your machine hasn't got. If you've edited your copy it writes options.nix.new beside it rather than overwriting your work.
• One line, no editor. haus set theme.accent teal writes the setting, type-checks it and rebuilds in one go; haus get reads one back and haus reset removes it. The haus CLI reference has the model.
• Ask for it in words. haus installs a skill that teaches a coding agent this whole surface, generated from the revision you run; see Changing your Mac with an agent.

The cookbook

The tour of what's worth knowing. Each block is host-file Nix.

Identity

haus.git.name = "Ada Lovelace";
haus.git.email = "ada@example.com";
haus.git.signingKey = "6F7BD6F43A7C1420";  # "" disables commit signing
haus.git.org = "analytical-engine";        # the GitHub owner your work lives under

org is the odd one out: not who you are, but where you work. gh-dash reads it to fill ⌘G's PR tabs with that owner's open, green, red and just-shipped work, so an org rename is one word rather than one per tab. On its own it does nothing: set haus.hearth.ghDash.enable = true alongside it, and keep the Git pack on (haus.developer.git.enable); that's what installs gh, and turning it off while the overlay is on stops the build.

The look

haus.theme.accent = "sapphire";     # any of the 14 Catppuccin accent names
haus.wallpaper.style = "minimal";   # none | minimal | orbits | constellation | flow | bold

The accent recolours lazygit, fzf, yazi, Glow, the browser and the generated desktop together, but not the terminal, and not the bar beyond its logo pill. Single-file dotfiles that bake a palette at their own theme slot (Ghostty, starship, tmux, bat, zellij) keep their built-in colour on purpose, and a flake check fails the build if one of them ever starts following. minimal is the desktop haus generates for you (a flat field in your palette, the ⌂ mark at its centre, a bloom in your accent), and "none" keeps the wallpaper you already have. The Appearance room has the whole palette and the desktop's own dials.

The terminal

haus.hearth.editorName = "neovim";          # the ONE editor: installed, and $EDITOR
haus.hearth.hijackFileAssociations = false; # make that editor the default file opener

More in the Development room.

Apps, windows and the launcher

haus.roster.slack = { key = "s"; name = "Slack"; cask = "slack"; };
haus.prowl.enable = true;          # false: no tiling, no Caps-Lock remap
haus.pounce.enable = true;         # false: ⌘Space stays Spotlight
haus.pounce.signingIdentity =      # sign it, and its Accessibility grant survives rebuilds
  "Developer ID Application: Ada Lovelace (ABCDE12345)";

The roster is the most common edit on the machine and has a page of its own.

The bar

haus.sill.enable = true;        # false: the native macOS menu bar stays
haus.sill.items.elgato = true;  # opt-in extras, see The bar

The optional pills are personal (an Elgato key-light toggle, a Harvest timer, an agents readout), so they're off unless you ask. The bar lists them.

Homebrew behaviour

haus.homebrew.cleanup = "none";    # none | uninstall | zap: what a rebuild does to undeclared apps
haus.homebrew.autoUpdate = false;  # brew update before each rebuild
haus.homebrew.upgrade = false;     # upgrade outdated packages each rebuild

cleanup is "none" so nothing you installed by hand is ever removed; "zap" gets you a fully declarative machine where an undeclared cask is uninstalled on the next rebuild.

Turning rooms off

Every room you can see has a switch, and turning one off leaves the rest working:

The macOS defaults, the Homebrew policy and the haus CLI itself are the foundation the rest stands on, and have no switch. Every room you can see does, and each one is off in the blank desktop, so what's on your Mac is whatever your desktop asked for plus whatever you did.

If what you want is tiling without its keyboard claims, don't switch the room off: set haus.keys.leader = "none" and haus.keys.windowNav = "none" instead, and prowl keeps arranging windows while Caps Lock stays Caps Lock. The launcher has the same escape: haus.keys.palette takes alt-space, ctrl-space or "none", and since only cmd-space displaces Spotlight, moving it is how you keep both. See rebinding.

Disagreeing with your desktop

Your host file wins. Anything the desktop chose, you change with a plain assignment (no lib.mkForce, no import order to reason about):

# the desktop set theme.accent = "mauve"; you'd rather have teal
haus.theme.accent = "teal";
haus.sill.enable = false;      # and no bar, thanks

That's the ladder doing its job: rooms declare defaults, a desktop states its choices above them, your host sits above both, and anything haus set writes sits above that. Switching desktops is one line in your flake; see Choose a desktop.

haus.snippets.matches = [
  { trigger = "@@"; replace = "ada@example.com"; }   # the desktop's, kept
  { trigger = ";sig"; replace = "— Ada"; }           # and mine
];

Bigger type

haus.appearance.largePrint = true is one named answer to a whole-machine question, and it pulls two complementary levers. haus.ui.scale moves haus's own type together (the terminal, the palette, the bar, the Dock, Finder's sidebar, the tiling gaps), and haus.displays.main.uiScale moves the display one step toward larger text, which enlarges everything including apps haus knows nothing about. They multiply, which is the intended effect and a bigger jump than either alone. hausdisp list prints the persistent UUIDs if you want to name one display rather than "main".

One limit is macOS's rather than haus's: the menu bar's height. There is no setting for it, so the bar's type follows ui.scale only so far and then stops. Making the whole bar bigger is what display scaling is for: it changes what a point means, which is the only thing that band responds to.

Beating a default haus set

haus sets Dock, Finder, trackpad and keyboard defaults, and every one is a soft default: set the same key plainly in your host file and yours wins.

# haus hides the Dock and puts it on the bottom. Put it on the left, always shown:
system.defaults.dock.autohide = false;
system.defaults.dock.orientation = "left";

Anything under system.defaults is fair game.

Secrets

Your config is text in a git repo, so secret values never go in it. haus declares which secrets exist and fetches them at runtime through secretspec:

secretspec check          # what's declared and still missing
secretspec set <NAME>     # fill one in

By default they live in this Mac's login keychain, which is why they don't ride along when you clone the config onto a second machine. Point haus.secrets.provider at a cloud vault if you'd rather they followed you.

cd ~/.config/nix
printf '#!/bin/sh\nexec gitleaks git --pre-commit --staged --redact --verbose\n' \
  > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit