Skip to content
LogoLogo

Quick Start

Installation

Add cattery as a flake input:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    cattery-modules.url = "https://flakehub.com/f/nixcafe/cattery-modules/*.tar.gz";
  };
}

NixOS (Full System)

The most common setup — full NixOS system with all modules available:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    cattery-modules.url = "https://flakehub.com/f/nixcafe/cattery-modules/*.tar.gz";
  };
 
  outputs = { nixpkgs, cattery-modules, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        cattery-modules.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}
# configuration.nix
{ ... }: {
  cattery = {
    room.desktop.dev.enable = true;
    user.name = "alice";
  };
}

Run nixos-rebuild switch and you're done.

home-manager (User-Level)

Standalone home-manager (Linux/macOS, no root access needed):

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    cattery-modules.url = "https://flakehub.com/f/nixcafe/cattery-modules/*.tar.gz";
  };
 
  outputs = { nixpkgs, home-manager, cattery-modules, ... }: {
    homeConfigurations.alice = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        cattery-modules.homeModules.default
        {
          cattery = {
            room.desktop.dev.enable = true;
            user.name = "alice";
          };
        }
      ];
    };
  };
}
home-manager switch --flake .#alice

nix-darwin (macOS)

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    darwin.url = "github:nix-darwin/nix-darwin";
    cattery-modules.url = "https://flakehub.com/f/nixcafe/cattery-modules/*.tar.gz";
  };
 
  outputs = { darwin, cattery-modules, ... }: {
    darwinConfigurations.macbook = darwin.lib.darwinSystem {
      system = "aarch64-darwin";
      modules = [
        cattery-modules.darwinModules.default
        {
          cattery = {
            room.basis.enable = true;
            user.name = "alice";
          };
        }
      ];
    };
  };
}
darwin-rebuild switch --flake .#macbook

NixOS-WSL

{
  cattery = {
    room.desktop.wsl.enable = true;
    user.name = "alice";
  };
}

Proxmox LXC Container

{
  cattery = {
    room.container.enable = true;
    system.proxmox.lxc.manageNetwork = true;
    user.name = "alice";
  };
}

Picking Individual Modules

Don't want a full room? Enable modules one at a time:

{
  cattery = {
    desktop.hyprland.enable = true;
    themes.catppuccin.enable = true;
    services.tailscale.enable = true;
    cli-apps.dev-kit.git.enable = true;
    cli-apps.dev-kit.rust.enable = true;
    cli-apps.shell.fish.enable = true;
    user.name = "alice";
  };
}

Customizing Rooms

Rooms use lib.mkDefault for sub-module enables — you can opt out of anything:

{
  cattery = {
    room.desktop.dev.enable = true;
    # Override room defaults:
    cli-apps.dev-kit.javascript.enable = false;  # I use bun standalone
    desktop.hyprland.enable = false;              # I prefer Niri
    desktop.niri.enable = true;
  };
}

Setting User Info

Many modules use cattery.user for defaults (git identity, email, GPG, shell):

{
  cattery.user = {
    name = "alice";
    email = {
      address = "[email protected]";
      userName = "Alice";
    };
    defaultUserShell = "fish";  # auto-enables fish module
    gpg.signKey = "ABCD1234";
  };
}

Next Steps

Suggest changes to this page