{"id":30304502,"url":"https://github.com/lawrab/nixos-config","last_synced_at":"2026-04-20T10:33:14.166Z","repository":{"id":308360567,"uuid":"1032349774","full_name":"lawrab/nixos-config","owner":"lawrab","description":"🏠 Complete NixOS + Hyprland desktop configuration with Flakes, Home Manager, and comprehensive documentation. Declarative dotfiles for a beautiful Wayland desktop experience.","archived":false,"fork":false,"pushed_at":"2025-12-14T22:20:04.000Z","size":18597,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T00:38:21.566Z","etag":null,"topics":["declarative","desktop-environment","dotfiles","home-manager","home-manager-config","hyprland-config","linux-customization","linux-desktop","nix-flake","nix-flakes","nixos","nixos-configuration","rice","wayland","window-manager"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lawrab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-05T07:18:21.000Z","updated_at":"2025-12-14T22:20:07.000Z","dependencies_parsed_at":"2025-08-23T12:48:28.485Z","dependency_job_id":"0bbcbc6d-0a43-4319-abaa-2887a3810e56","html_url":"https://github.com/lawrab/nixos-config","commit_stats":null,"previous_names":["lawrab/nixos-config"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lawrab/nixos-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrab%2Fnixos-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrab%2Fnixos-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrab%2Fnixos-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrab%2Fnixos-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lawrab","download_url":"https://codeload.github.com/lawrab/nixos-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrab%2Fnixos-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32043065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["declarative","desktop-environment","dotfiles","home-manager","home-manager-config","hyprland-config","linux-customization","linux-desktop","nix-flake","nix-flakes","nixos","nixos-configuration","rice","wayland","window-manager"],"created_at":"2025-08-17T07:09:03.586Z","updated_at":"2026-04-20T10:33:14.155Z","avatar_url":"https://github.com/lawrab.png","language":"Nix","readme":"\u003cdiv align=\"center\"\u003e\n\n# NixOS Configuration with Hyprland - A Declarative Desktop Journey\n\n⚠️ **GPU Undervolting Warning**: This configuration includes GPU undervolting settings that automatically limit the NVIDIA GPU clock speed to 1905 MHz. This is configured for a specific hardware setup and may not be suitable for all systems. See the [GPU Configuration section](#-gpu-configuration--undervolting) below for instructions on how to disable or modify this setting.\n\n**Welcome to my personal NixOS and Linux customisation adventure!**\n\nThis repository is the living blueprint of my desktop, crafted with [NixOS](https://nixos.org/) and [Hyprland](https://hyprland.org/). It's a constantly evolving setup designed for a lightweight, keyboard-driven, and visually cohesive Wayland desktop experience with flakes, Home Manager, and comprehensive dotfiles.\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![NixOS](https://img.shields.io/badge/NixOS-unstable-blue?logo=nixos\u0026style=for-the-badge)](https://nixos.org/channels/nixos-unstable)\n[![Hyprland](https://img.shields.io/badge/Hyprland-Window%20Manager-8c8cff?logo=linux\u0026style=for-the-badge)](https://hyprland.org/)\n[![Flakes](https://img.shields.io/badge/Nix-Flakes-blueviolet?logo=nixos\u0026style=for-the-badge)](https://nixos.wiki/wiki/Flakes)\n[![Home Manager](https://img.shields.io/badge/Home%20Manager-Enabled-brightgreen?logo=nixos\u0026style=for-the-badge)](https://github.com/nix-community/home-manager)\n[![Catppuccin](https://img.shields.io/badge/Catppuccin-Mocha-f5c2e7?logo=catppuccin\u0026style=for-the-badge)](https://catppuccin.com/)\n\n[![Licence: MIT](https://img.shields.io/github/license/lawrab/nixos-config?style=for-the-badge)](./LICENSE)\n[![Last Commit](https://img.shields.io/github/last-commit/lawrab/nixos-config?style=for-the-badge)](https://github.com/lawrab/nixos-config/commits/main)\n[![Repo Size](https://img.shields.io/github/repo-size/lawrab/nixos-config?style=for-the-badge)](https://github.com/lawrab/nixos-config)\n[![Maintained](https://img.shields.io/maintenance/yes/2025?style=for-the-badge)](https://github.com/lawrab/nixos-config/commits/main)\n\n\u003c/div\u003e\n\n\u003e **A Friendly Disclaimer:**  \n\u003e I'm a NixOS and Linux customisation enthusiast, not an expert. This setup is my learning playground and is guaranteed to contain experiments, quirks, and maybe even a few dragons. Please use it as inspiration, but always double-check before adopting anything critical for your own system!\n\n---\n\n## Table of Contents\n- [What's Inside? A Look at the Tech Stack](#-whats-inside-a-look-at-the-tech-stack)\n- [Blueprint: How It's All Organised](#️-blueprint-how-its-all-organised)\n- [Phase 2: Project-Based Development Workflow](#-phase-2-project-based-development-workflow)\n- [Configuration Documentation](#-configuration-documentation)\n- [The Heart of the Look: Theming](#-the-heart-of-the-look-theming)\n- [Using Unstable Packages](#-using-unstable-packages)\n- [Secrets Management](#-secrets-management)\n- [Network Storage Configuration](#-network-storage-configuration)\n- [GPU Configuration \u0026 Undervolting](#-gpu-configuration--undervolting)\n- [Installation Guide](#-installation-guide)\n- [Troubleshooting \u0026 FAQ](#-troubleshooting--faq)\n- [A Glimpse of the Desktop](#-a-glimpse-of-the-desktop)\n- [Key Features \u0026 Topics](#-key-features--topics)\n- [Acknowledgements](#-acknowledgements)\n- [Licence](#-licence)\n\n---\n\n## ✨ What's Inside? NixOS Hyprland Tech Stack\n\nThis NixOS configuration brings together carefully chosen tools to create a seamless Wayland desktop environment optimised for developers and power users.\n\n| Category          | Component                                                                                              |\n| ----------------- | ------------------------------------------------------------------------------------------------------ |\n| **Core System**   | **OS:** [NixOS](https://nixos.org/) (Unstable) │ **WM:** [Hyprland](./home/hyprland.nix) │ **Audio:** [PipeWire](https://pipewire.org/)          |\n| **Visuals**       | **Bar:** [Waybar](./home/waybar.nix) │ **Lock Screen:** [Hyprlock](./hyprlock/hyprlock.nix) │ **Wallpaper:** [swww](./swww/swww.nix) |\n| **Terminal \u0026 Shell** | **Terminal:** [Kitty](./home/kitty.nix) │ **Shell:** [Zsh](./home/shell.nix) + [Oh My Zsh](https://ohmyz.sh/) │ **Prompt:** [Starship](https://starship.rs/) |\n| **Tooling**       | **Launcher:** [Wofi](./home/wofi.nix) │ **Notifications:** [Mako](https://github.com/emersion/mako) │ **File Manager:** [Thunar](https://docs.xfce.org/xfce/thunar/start) |\n| **Gaming \u0026 Apps** | **Gaming:** Steam, ProtonUp-Qt, Gamemode │ **Image Viewer:** [Loupe](https://gitlab.gnome.org/GNOME/loupe) │ **Passwords:** 1Password |\n| **Audio Production** | **Editing:** [Audacity](https://www.audacityteam.org/), [Reaper](https://www.reaper.fm/) │ **Conversion:** FFmpeg, SoX │ **Playback:** VLC |\n\n*...plus a custom [screenshot script](./home/scripts.nix), hand-picked fonts, and countless quality-of-life tweaks!*\n\n---\n\n## 🗺️ NixOS Configuration Structure \u0026 Organization\n\nThis flake-based NixOS configuration is designed with modularity and clarity in mind, making it easy for others to navigate, understand, and adapt.\n\n```\n.\n├── flake.nix                # ❄️ Main flake entrypoint, defines inputs and outputs\n├── configuration.nix        # ⚙️ System-wide settings and module imports\n├── home.nix                 # 🏠 Home Manager integration and user module imports\n├── system-packages.nix      # 📦 System-wide packages (nfs-utils, cifs-utils, etc.)\n├── mounts.nix               # 💾 Network filesystem mounts (NFS/SMB shares)\n├── ollama.nix               # 🤖 Local AI model server configuration (disabled by default)\n│\n├── home/                    # 🧑‍💻 User-specific application configs (dotfiles)\n│   ├── browsers.nix         # 🌐 Firefox \u0026 Brave browser configuration\n│   ├── hyprland.nix         # 🪟 Window manager rules and keybindings\n│   ├── waybar.nix           # 📊 Status bar modules and styling\n│   ├── packages.nix         # 📦 Essential system packages (lightweight)\n│   ├── direnv.nix           # 🔄 Development environment management\n│   ├── cli-tools.nix        # 🎨 Catppuccin theming for CLI tools\n│   ├── environment.nix      # 🔧 Environment variables and shell setup\n│   ├── shell.nix            # 🐚 Zsh configuration and aliases\n│   ├── gtk.nix              # 🎨 GTK theming with consolidated CSS\n│   ├── scripts.nix          # 📜 Custom shell scripts and utilities\n│   ├── vscode.nix           # 💻 VSCode with direnv integration\n│   └── ...and more application configs\n│\n├── dev-templates/           # 🚀 Project-specific development environments\n│   ├── python-ml/           # 🐍 Machine learning environment\n│   ├── python-web/          # 🌐 Web development environment\n│   └── nodejs/              # ⚡ Node.js development environment\n│\n├── theme/\n│   └── theme.nix            # 🎨 Fallback colors for non-Catppuccin apps\n│\n└── screenshots/\n    └── hyprland-layout.png  # 🖼️ Desktop preview\n```\n\n---\n\n## 🚀 Phase 2: Project-Based Development Workflow\n\nThis configuration implements a **Phase 2** approach to NixOS development environments, moving from system-wide package installation to project-specific, reproducible development environments using Nix flakes and direnv.\n\n### Why Phase 2?\n\n**Traditional Approach (Phase 1):**\n- ❌ Heavy system-wide package installation (67+ Python packages)\n- ❌ Slow system rebuilds due to compilation\n- ❌ Version conflicts between projects\n- ❌ Difficult to share exact development environments\n\n**Phase 2 Approach:**\n- ✅ **~80% faster system rebuilds** - only essential tools installed globally\n- ✅ **Project isolation** - each project has its own environment\n- ✅ **Reproducible environments** - exact dependencies defined per project\n- ✅ **Instant environment switching** - automatic loading via direnv\n- ✅ **Shareable setups** - teammates get identical environments\n\n### How It Works\n\n#### 1. Lightweight System Configuration\nThe system now only includes essential development tools globally:\n```nix\n# Only essential tools installed system-wide\nclaude-code        # AI coding assistant\nuv                 # Python package manager\npython3            # Base Python interpreter\n```\n\nAll heavy development packages (numpy, pandas, nodejs, etc.) have been moved to project-specific flakes.\n\n#### 2. Development Templates\nPre-configured development environments for common use cases:\n\n| Template | Use Case | Included Packages |\n|----------|----------|-------------------|\n| **python-ml** | Machine Learning | numpy, pandas, scikit-learn, matplotlib, jupyter, opencv |\n| **python-web** | Web Development | flask, django, fastapi, sqlalchemy, postgresql, redis |\n| **nodejs** | JavaScript/TypeScript | nodejs, typescript, vite, eslint, prettier, jest |\n\n#### 3. The `dev-init` Workflow\n\n**Quick Start:**\n```bash\n# Create a new project\nmkdir my-ml-project \u0026\u0026 cd my-ml-project\n\n# Initialize with template\ndev-init python-ml\n\n# Environment automatically loads!\n# You now have access to all ML packages\npython -c \"import numpy; print('NumPy ready!')\"\n```\n\n**What happens behind the scenes:**\n1. `dev-init` copies the appropriate `flake.nix` template\n2. Creates `.envrc` file for direnv integration\n3. Automatically allows direnv to load the environment\n4. Environment becomes active immediately\n\n#### 4. Automatic Environment Management\n\n**Direnv Integration:**\n- **Automatic loading**: Environment activates when entering project directory\n- **Automatic unloading**: Environment deactivates when leaving project\n- **VSCode integration**: Automatic environment detection in editor\n- **Shell integration**: Works seamlessly with bash/zsh\n\n**Example Workflow:**\n```bash\n# Navigate to project - environment loads automatically\ncd ~/projects/my-ml-project\n# → 🐍 Python ML environment loaded\n# → Python: 3.12.x\n# → Available packages: numpy, pandas, scikit-learn...\n\n# Start coding immediately\njupyter lab\n# All packages available, no installation needed\n\n# Leave project - environment unloads automatically\ncd ~/\n# → Environment deactivated\n```\n\n#### 5. VSCode Integration\n\nThe configuration includes automatic VSCode integration:\n- **Direnv extension**: Automatic environment detection\n- **Enhanced Nix support**: Syntax highlighting and language server\n- **Python integration**: Automatic virtual environment detection\n- **Settings sync**: Consistent settings across all development environments\n\n### Creating Custom Templates\n\n**Add your own development environment:**\n\n1. **Create template directory:**\n   ```bash\n   mkdir ~/nixos-config/dev-templates/my-template\n   ```\n\n2. **Create flake.nix:**\n   ```nix\n   {\n     description = \"My Custom Development Environment\";\n     \n     inputs = {\n       nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n       flake-utils.url = \"github:numtide/flake-utils\";\n     };\n\n     outputs = { nixpkgs, flake-utils, ... }:\n       flake-utils.lib.eachDefaultSystem (system:\n         let pkgs = nixpkgs.legacyPackages.${system};\n         in {\n           devShells.default = pkgs.mkShell {\n             buildInputs = with pkgs; [\n               # Your packages here\n             ];\n             \n             shellHook = ''\n               echo \"🚀 My custom environment loaded\"\n               # Your initialization commands\n             '';\n           };\n         });\n   }\n   ```\n\n3. **Use your template:**\n   ```bash\n   dev-init my-template\n   ```\n\n### Advanced Usage\n\n**Manual Environment Management:**\n```bash\n# Enter environment manually\nnix develop\n\n# Check what's available\nwhich python\npip list\n\n# Exit environment\nexit\n```\n\n**Environment Customization:**\n```bash\n# Edit project-specific packages\nnano flake.nix\n\n# Reload environment\ndirenv reload\n```\n\n**Sharing Environments:**\n```bash\n# Share flake.nix with teammates\ngit add flake.nix .envrc\ngit commit -m \"Add development environment\"\n\n# Teammates get identical environment\ngit clone project \u0026\u0026 cd project\n# Environment automatically loads with exact same packages\n```\n\n### Migration Guide\n\n**For existing projects:**\n\n1. **Backup current setup:**\n   ```bash\n   pip freeze \u003e requirements.txt  # Save current packages\n   ```\n\n2. **Initialize development environment:**\n   ```bash\n   dev-init python-ml  # or appropriate template\n   ```\n\n3. **Customize as needed:**\n   ```bash\n   nano flake.nix  # Add any missing packages\n   direnv reload   # Apply changes\n   ```\n\n4. **Verify environment:**\n   ```bash\n   python -c \"import your_packages\"  # Test imports\n   ```\n\nThis Phase 2 approach transforms your system from a \"development workstation\" to a \"development platform\" - cleaner, faster, and infinitely more maintainable!\n\n---\n\n## 📚 Configuration Documentation\n\nAll configuration files include comprehensive inline documentation to help you understand NixOS-specific patterns and quirks. Key files are documented with:\n\n### Core System Files\n- **[`flake.nix`](./flake.nix)** - Main flake configuration with binary caches, channel mixing, and module organisation\n- **[`configuration.nix`](./configuration.nix)** - System-wide settings including bootloader, networking, audio, graphics, and user management\n- **[`home.nix`](./home.nix)** - Home Manager integration and user module imports\n\n### Key User Configuration Files\n- **[`home/browsers.nix`](./home/browsers.nix)** - Consolidated Firefox and Brave configuration with matching settings\n- **[`home/packages.nix`](./home/packages.nix)** - User packages organized by category (utilities, development, gaming, etc.)\n- **[`home/environment.nix`](./home/environment.nix)** - Environment variables for Wayland compatibility and dark mode\n- **[`home/shell.nix`](./home/shell.nix)** - Zsh configuration with Oh My Zsh, aliases, and shell integrations\n- **[`home/gtk.nix`](./home/gtk.nix)** - GTK theming with consolidated CSS for consistent dark mode\n\n### Application Configurations\nEach configuration file in the `home/` directory includes documentation for:\n- **NixOS-specific patterns** - `writeShellScriptBin`, service integration, and package organization\n- **Wayland-first approach** - Native Wayland tools (Mako, grim/slurp) instead of X11 alternatives\n- **Modular design** - Clean separation of concerns with consolidated configurations\n- **Theme consistency** - Centralized theming system propagated across all applications\n- **Package categorization** - Organized by stability (stable vs unstable) and purpose\n- **Environment variables** - Proper Wayland compatibility and dark mode enforcement\n\n### Recent Optimizations (2025)\nThe configuration has been recently optimized for:\n- **Consolidated theming** - GTK CSS shared between GTK3/GTK4, unified dark mode variables\n- **Organized packages** - Categorized by function with clear stable/unstable separation  \n- **Streamlined shell setup** - Unified zsh initialization without conflicts\n- **Browser consolidation** - Firefox and Brave managed together with matching configurations\n- **Environment cleanup** - All user environment variables managed in one location\n\nThe documentation focuses on **why** things are configured a certain way rather than just **what** each option does, making it easier for others to understand and adapt the configuration.\n\n---\n\n## 🎨 The Heart of the Look: Official Catppuccin Theming\n\nThis configuration now uses the **official [Catppuccin/nix](https://github.com/catppuccin/nix) modules** for consistent theming across all supported applications. The setup provides:\n\n### Official Catppuccin Integration\n- **Centralized theming** via `catppuccin/nix` flake input\n- **System-wide Catppuccin Mocha** color scheme applied consistently\n- **Native module support** for applications like Firefox, Neovim, Kitty, Waybar, and more\n- **Automatic color coordination** - all applications use the same official Catppuccin palette\n\n### Supported Applications with Native Catppuccin Theming\n- **Terminal**: Kitty terminal with Catppuccin Mocha\n- **Editors**: Neovim with official Catppuccin plugin\n- **Browsers**: Firefox with Catppuccin theme\n- **Desktop**: Hyprland window manager borders and styling\n- **Status Bar**: Waybar with Catppuccin CSS integration\n- **CLI Tools**: bat, btop, fzf with matching themes\n- **Development**: VS Code with Catppuccin color profile\n\n### Fallback Theme System\nThe [`theme/theme.nix`](theme/theme.nix) file now serves as a **fallback** for applications that don't yet have official Catppuccin/nix module support (like wofi, thunar, etc.). It contains the official Catppuccin Mocha color definitions for manual theming of unsupported applications.\n\n### Global Theme Configuration\nThe theming is controlled through a single `catppuccin` configuration in [`home.nix`](home.nix):\n\n```nix\ncatppuccin = {\n  enable = true;\n  flavor = \"mocha\";    # Dark theme\n  accent = \"mauve\";    # Purple accent color\n};\n```\n\nThis ensures perfect color consistency across the entire desktop environment using the official Catppuccin color specifications.\n\n---\n\n## 📦 Package Management Strategy\n\nThis configuration implements a **three-tier package management approach** that balances system stability, development flexibility, and performance.\n\n### Package Management Tiers\n\n#### Tier 1: Essential System Packages (Stable Channel)\n**Location:** `home/packages.nix`  \n**Purpose:** Core desktop functionality and utilities\n\n```nix\n# System utilities (stable for reliability)\n- libnotify, pwvucontrol, thunar\n- btop, lm_sensors, eza, bat, fzf\n- Font packages and themes\n```\n\n#### Tier 2: Applications \u0026 Tools (Unstable Channel)\n**Location:** `home/packages.nix`  \n**Purpose:** Desktop applications that benefit from latest features\n\n```nix\n# Applications (unstable for latest features)\n- claude-code, steam, discord, obsidian\n- grim, slurp, vlc, reaper\n- Gaming and productivity tools\n```\n\n#### Tier 3: Development Environments (Project-Specific Flakes)\n**Location:** `dev-templates/` and individual projects  \n**Purpose:** Isolated, reproducible development environments\n\n```nix\n# Development packages (project-specific)\n- python packages (numpy, pandas, flask, etc.)\n- nodejs and npm packages\n- Language-specific tools and frameworks\n```\n\n### The Flake.nix Channel Strategy\n\nThe configuration defines two package sources:\n- **`pkgs`** - Stable packages from NixOS 25.05 (system reliability)\n- **`pkgs-unstable`** - Latest packages from nixos-unstable (features \u0026 security)\n\n### When to Use Each Approach\n\n| Use Case | Approach | Example |\n|----------|----------|---------|\n| **Core utilities** | Stable packages in `packages.nix` | File manager, terminal tools |\n| **Desktop apps** | Unstable packages in `packages.nix` | Discord, Steam, browsers |\n| **Development** | Project-specific flakes | Python ML, web frameworks |\n| **System tools** | Stable system packages | Network drivers, core services |\n\n### Adding Packages\n\n#### For System-Wide Packages:\n```nix\n# In home/packages.nix - add to appropriate section\n(with pkgs; [\n  your-stable-package    # Stable channel\n]) ++\n(with pkgs-unstable; [\n  your-latest-package    # Unstable channel\n])\n```\n\n#### For Development Packages:\n```bash\n# Use project-specific flakes instead\ndev-init python-ml     # Get numpy, pandas, etc.\ndev-init nodejs        # Get node, typescript, etc.\n\n# Or create custom template for your specific needs\n```\n\n### Migration from Global Development Packages\n\n**What Changed:**\n- ❌ **Removed:** 67+ Python packages from global installation\n- ❌ **Removed:** Node.js and npm from system packages  \n- ✅ **Added:** Project-specific development environments\n- ✅ **Added:** Automatic environment switching via direnv\n\n**Benefits:**\n- **~80% faster system rebuilds** - no more compiling scientific Python packages\n- **Zero version conflicts** - each project has isolated dependencies\n- **Perfect reproducibility** - exact same environment on every machine\n- **Easier maintenance** - update development tools per-project, not system-wide\n\n### Package Discovery\n\n**Finding packages:**\n```bash\n# Search nixpkgs\nnix search nixpkgs python3Packages.numpy\n\n# Check what's available in templates\ndev-init  # Shows available templates\n\n# Browse template contents\ncat ~/nixos-config/dev-templates/python-ml/flake.nix\n```\n\nThis approach gives you the best of all worlds: a fast, stable system with flexible, isolated development environments!\n\n---\n\n## 🔒 Secrets Management\n\nThis configuration includes support for managing sensitive information like API keys through shell environment variables using a simple `~/.env` file approach.\n\n### How It Works\n\nThe system is configured to automatically source a `~/.env` file from your home directory on shell startup (both bash and zsh). This file is not created automatically - you create it yourself when needed.\n\n### Setting Up Secrets\n\n1. **Build your system first:**\n\n```bash\nsudo nixos-rebuild switch --flake ~/nixos-config#larry-desktop\n```\n\n2. **Create your environment file using the provided script:**\n\n```bash\ncreate-env\n```\n\nThis interactive script will prompt you for each environment variable and only add the ones you provide values for.\n\n3. **Or create the file manually:**\n\n```bash\nnano ~/.env\n```\n\nAdd your environment variables:\n\n```bash\n# ~/.env - User environment variables\nexport ANTHROPIC_API_KEY=\"your-actual-api-key-here\"\nexport LAMETRIC_API_KEY=\"your-actual-lametric-key-here\"\nexport LAMETRIC_IP=\"your-lametric-device-ip-here\"\n```\n\n4. **Set secure permissions:**\n\n```bash\nchmod 600 ~/.env\n```\n\n5. **Load in current session:**\n\n```bash\nsource ~/.env\n```\n\n### Supported Environment Variables\n\nCurrently, the configuration supports:\n- `ANTHROPIC_API_KEY` - For Claude AI integration\n- `LAMETRIC_API_KEY` - For LaMetric device integration\n- `LAMETRIC_IP` - LaMetric device IP address\n\n### Security Notes\n\n- The `.env` file is in your writable home directory, not in the git repository\n- Variables are loaded as environment variables in your shell sessions\n- Only variables you explicitly set are included in the file\n- If you don't need environment variables, the system works perfectly without the file\n- The `create-env` script automatically backs up existing files before recreating\n\n### Disabling LaMetric Integration\n\nIf you don't have a LaMetric Time device, you can disable the LaMetric music controls in Waybar:\n\n1. **Edit the Waybar configuration:**\n   ```bash\n   nano ~/nixos-config/home/waybar.nix\n   ```\n\n2. **Remove LaMetric from modules-left:**\n   ```nix\n   # Change this line:\n   modules-left = [ \"hyprland/workspaces\" \"mpris\" \"custom/lametric-music\" ];\n   \n   # To this:\n   modules-left = [ \"hyprland/workspaces\" \"mpris\" ];\n   ```\n\n3. **Remove the LaMetric module configuration (optional):**\n   You can also remove the entire `\"custom/lametric-music\"` section and its styling to clean up the configuration.\n\n4. **Rebuild your system:**\n   ```bash\n   sudo nixos-rebuild switch\n   ```\n\nThe LaMetric scripts (`lametric-music` and `lametric-notify`) will still be available in case you get a device later, but they won't appear in your status bar.\n\n---\n\n## 💾 Network Storage Configuration\n\nThis configuration includes support for NFS and SMB/CIFS network storage mounts, managed through a dedicated `mounts.nix` file.\n\n### Current Configuration\n\nThe repository includes a **personal NFS mount** configured for my specific setup:\n\n- **Mount Point**: `/mnt/rabnas`\n- **NFS Share**: `rabnas.home:/volume1/data`\n- **Auto-mounting**: Mounts automatically when accessed, unmounts after 60 seconds of inactivity\n\n### Using This Repository as a Template\n\n⚠️ **Important**: If you're using this repository as a template, you'll need to modify or remove the NFS configuration:\n\n#### Option 1: Remove NFS Mount (Recommended for most users)\n\n1. **Delete the mount configuration** by removing the `fileSystems` section in [`mounts.nix`](./mounts.nix)\n2. **Keep the file structure** - the empty file won't cause issues\n3. **Remove system packages** (optional) - edit [`system-packages.nix`](./system-packages.nix) to remove `nfs-utils` and `cifs-utils` if you don't need them\n\n#### Option 2: Configure Your Own NFS/SMB Mounts\n\n1. **Edit [`mounts.nix`](./mounts.nix)** and update:\n   - `device = \"your-nas-hostname:/path/to/share\";` - Replace with your NAS details\n   - `\"/mnt/rabnas\"` - Change to your preferred mount point\n   - Add additional mounts as needed\n\n2. **Example configurations** are included in the file for:\n   - Additional NFS shares\n   - SMB/CIFS shares with authentication\n\n### Mount Features\n\n- **Auto-mounting**: Uses systemd automount for on-demand mounting\n- **Timeouts**: Reasonable timeouts prevent hanging if NAS is unavailable\n- **No boot mounting**: Mounts won't delay system startup\n- **Automatic unmounting**: Saves resources by unmounting idle shares\n\n### Testing Your Configuration\n\nAfter rebuilding your system, test the mount:\n\n```bash\n# Check if mount point exists\nls -la /mnt/rabnas\n\n# Access the share to trigger auto-mount\ncd /mnt/rabnas\n\n# Check mount status\nmount | grep rabnas\n```\n\n---\n\n## ⚙️ GPU Configuration \u0026 Undervolting\n\nThis configuration includes GPU undervolting settings specifically configured for NVIDIA graphics cards. The system automatically limits the GPU clock speed to 1905 MHz on boot.\n\n### Current GPU Configuration\n\nThe configuration includes:\n- **Coolbits \"28\"** - Enables GPU overclocking/undervolting controls\n- **Power Management** - Basic NVIDIA power management features  \n- **Automatic Clock Limiting** - Systemd service that sets GPU clock to 1905 MHz on startup\n\n### ⚠️ Important Hardware Compatibility Notes\n\n**This GPU configuration is specific to my hardware setup and may not be appropriate for your system.** Different graphics cards have different safe operating limits.\n\n### How to Disable GPU Undervolting\n\nIf you want to use this configuration but don't want the GPU undervolting, follow these steps:\n\n#### Option 1: Disable the Systemd Service Only\n\nTo keep NVIDIA drivers but remove automatic undervolting:\n\n1. **Edit configuration.nix:**\n   ```bash\n   nano ~/nixos-config/configuration.nix\n   ```\n\n2. **Comment out or remove the entire systemd service section:**\n   ```nix\n   # GPU clock speed configuration via systemd service\n   # systemd.services.gpu-undervolt = {\n   #   description = \"GPU Undervolting Service\";\n   #   after = [ \"graphical-session.target\" ];\n   #   wantedBy = [ \"multi-user.target\" ];\n   #   serviceConfig = {\n   #     Type = \"oneshot\";\n   #     RemainAfterExit = true;\n   #     ExecStart = \"/run/current-system/sw/bin/nvidia-smi -lgc 1905\";\n   #     User = \"root\";\n   #   };\n   # };\n   ```\n\n3. **Rebuild your system:**\n   ```bash\n   sudo nixos-rebuild switch\n   ```\n\n#### Option 2: Disable Coolbits (Remove Overclocking Controls)\n\nTo also remove the ability to modify GPU clocks manually:\n\n1. **Edit configuration.nix and remove the screenSection:**\n   ```nix\n   # Remove or comment out these lines:\n   # services.xserver.screenSection = ''\n   #   Option \"Coolbits\" \"28\"\n   # '';\n   ```\n\n2. **Rebuild your system:**\n   ```bash\n   sudo nixos-rebuild switch\n   ```\n\n#### Option 3: Different Hardware (AMD/Intel)\n\nIf you have AMD or Intel graphics instead of NVIDIA:\n\n1. **Remove the entire NVIDIA configuration section** from `configuration.nix`:\n   ```nix\n   # Remove these sections:\n   # services.xserver.videoDrivers = [ \"nvidia\" ];\n   # services.xserver.screenSection = ''\n   #   Option \"Coolbits\" \"28\"\n   # '';\n   # hardware.nvidia = { ... };\n   # systemd.services.gpu-undervolt = { ... };\n   ```\n\n2. **For AMD graphics, add:**\n   ```nix\n   services.xserver.videoDrivers = [ \"amdgpu\" ];\n   ```\n\n3. **For Intel graphics, add:**\n   ```nix\n   services.xserver.videoDrivers = [ \"intel\" ];\n   ```\n\n### Modifying Clock Speeds for Your Hardware\n\nIf you want to keep undervolting but adjust the clock speed for your specific GPU:\n\n1. **Research your GPU's safe operating limits** using tools like:\n   - `nvidia-smi -q -d CLOCK` - Check current clock speeds\n   - GPU-Z or similar tools to find your card's specifications\n   - Online forums and reviews for your specific GPU model\n\n2. **Edit the clock speed** in the systemd service:\n   ```nix\n   ExecStart = \"/run/current-system/sw/bin/nvidia-smi -lgc YOUR_SAFE_CLOCK_SPEED\";\n   ```\n\n3. **Test thoroughly** after rebuilding to ensure system stability\n\n### Manual GPU Control\n\nWith Coolbits enabled, you can manually control GPU settings using:\n\n- **nvidia-settings** - GUI for GPU configuration\n- **nvidia-smi** - Command line GPU management\n  ```bash\n  nvidia-smi -lgc 1800   # Set graphics clock to 1800 MHz\n  nvidia-smi -q          # Query current GPU status\n  ```\n\n---\n\n## 🚀 Installation Guide\n\nReady to give it a try? Here's how you can get this setup running.\n\n\u003e **Prerequisite:** A running NixOS system with flakes enabled.\n\n### ⚠️ A Note on Build Times\n\nThis configuration includes an *optional* setup for the [Ollama](https://ollama.com/) service to run large language models locally.\n\n**Warning:** Building the system with Ollama enabled will trigger a **very long build time** (potentially an hour) for the first installation. This is because it needs to compile the entire CUDA toolkit from source if a pre-built binary is not available for your system.\n\n#### How to Disable Ollama\n\nIf you do not want to build with Ollama, you can disable it with a one-line change.\n\n1.  Open the `configuration.nix` file.\n2.  Find the `imports` section at the top of the file.\n3.  Add a `#` to the beginning of the `./ollama.nix` line to comment it out, like so:\n\n    ```nix\n    imports = [\n      ./hardware-configuration.nix\n      ./environment.nix\n      ./home.nix\n    \n      # --- Optional Services ---\n      # Uncomment the line below to enable the Ollama service.\n      # Be aware: this will trigger a very long build the first time.\n      # ./ollama.nix \n    ];\n    ```\n4.  Save the file and rebuild your system as normal.\n\n### Step 1: Clone the Repository\n\n```bash\ngit clone https://github.com/lawrab/nixos-config.git ~/nixos-config\ncd ~/nixos-config\n```\n\n### Step 2: Update the Hostname\n\nMy configuration is set up for a machine with the hostname `larry-desktop`. You'll need to change this to match your own.\n\n1.  **Find your hostname:** Run `hostname` in your terminal.\n2.  **Update the flake:** Open `flake.nix` and change `\"larry-desktop\"` to your hostname.\n\n### Step 3: Configure Environment Variables (Optional - After Build)\n\nIf you want to use features that require API keys, you can set them up after building:\n\n1. **Use the interactive script to create your environment file:**\n   ```bash\n   create-env\n   ```\n\n2. **Or create the file manually:**\n   ```bash\n   nano ~/.env\n   chmod 600 ~/.env\n   ```\n\n3. **Load in current session:**\n   ```bash\n   source ~/.env\n   ```\n\n\u003e **Note:** This step is completely optional. The system will build and work perfectly without any environment variables configured.\n\n### Step 4: Rebuild the System\n\nThere are two ways to apply this configuration:\n\n#### Method A: The Symlink Approach (Recommended)\n\nThis is the most convenient method for managing your system config. It makes your cloned folder the direct source of truth for NixOS.\n\n1.  **Back up your current config:**\n    ```bash\n    sudo mv /etc/nixos /etc/nixos.bak\n    ```\n2.  **Create a symbolic link:**\n    ```bash\n    sudo ln -s ~/nixos-config /etc/nixos\n    ```\n3.  **Rebuild your system:**\n    ```bash\n    sudo nixos-rebuild switch\n    ```\n\n#### Method B: The Pure Flake Approach\n\nThis method is great if you don't want to touch `/etc/nixos` and prefer to specify the path every time.\n\n```bash\nsudo nixos-rebuild switch --flake ~/nixos-config#your-hostname\n```\n\n### Step 5: Test the Development Workflow (New in Phase 2)\n\nAfter rebuilding, test the new development environment system:\n\n1. **Check that dev-init is available:**\n   ```bash\n   dev-init  # Should show available templates\n   ```\n\n2. **Test a development environment:**\n   ```bash\n   # Create test project\n   mkdir ~/test-ml \u0026\u0026 cd ~/test-ml\n   \n   # Initialize Python ML environment\n   dev-init python-ml\n   \n   # Verify packages are available\n   python -c \"import numpy, pandas; print('✅ ML environment working!')\"\n   ```\n\n3. **Test environment switching:**\n   ```bash\n   # Leave project directory\n   cd ~/\n   # Try importing - should fail (environment unloaded)\n   python -c \"import numpy\" || echo \"✅ Environment properly isolated\"\n   \n   # Re-enter project\n   cd ~/test-ml\n   # Should work again\n   python -c \"import numpy; print('✅ Environment auto-loaded!')\"\n   ```\n\n4. **Test VSCode integration:**\n   ```bash\n   # Open project in VSCode\n   cd ~/test-ml \u0026\u0026 code .\n   # VSCode should automatically detect the Python environment\n   ```\n\n### Step 6: Automatic Maintenance (Optional Setup)\n\nYour system is now configured with automatic maintenance features:\n\n- **🗑️ Garbage Collection**: Runs weekly (Sundays at 03:15) and aggressively keeps only the last 3 generations\n- **🔄 System Updates**: Daily updates (04:30 ±30min) pull the latest configuration from your GitHub repository\n- **🛠️ Store Optimization**: Automatically deduplicates files to save disk space\n\n**Important Notes:**\n- Updates will only apply if your PC is on at the scheduled times, otherwise they'll run at next boot\n- No automatic reboots - you'll need to manually restart for kernel updates\n- Manual cleanup: `sudo nix-collect-garbage -d` (system) and `nix-collect-garbage -d` (home-manager)\n\n---\n\n## ❔ Troubleshooting \u0026 FAQ\n\n### Common Issues\n\n-   **\"flakes are not enabled\" error:** If you get this error, you need to enable flakes in your `configuration.nix`. Add the following to your system configuration:\n    ```nix\n    nix.settings.experimental-features = [ \"nix-command\" \"flakes\" ];\n    ```\n-   **`nixos-rebuild` fails:** The build can fail for many reasons. Carefully read the error output, as it often points to the exact problem.\n\n### Environment Variable Issues\n\n-   **Environment variables not available:** Make sure you've created `~/.env` with your actual API keys and either restarted your shell or run `source ~/.env`.\n-   **Script not found:** If `create-env` command isn't found, rebuild your system first to install the script.\n-   **Permission denied on .env:** Run `chmod 600 ~/.env` to fix file permissions.\n\n### Development Environment Issues\n\n-   **`dev-init` command not found:** Rebuild your system to install the script: `sudo nixos-rebuild switch`\n-   **Environment not loading automatically:** \n    - Check if direnv is running: `direnv status`\n    - Allow direnv in the project: `direnv allow`\n    - Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`\n-   **Packages not available in development environment:**\n    - Ensure you're in the project directory\n    - Check if `.envrc` exists: `ls -la .envrc`\n    - Reload environment: `direnv reload`\n    - Manually enter environment: `nix develop`\n-   **VSCode not detecting Python environment:**\n    - Install direnv extension for VSCode\n    - Restart VSCode after entering project directory\n    - Check Python interpreter path in VSCode settings\n-   **Template not found:** Check available templates with `dev-init` (no arguments)\n-   **Import errors in development environment:**\n    - Verify environment is active: check your shell prompt\n    - List available packages: `pip list` or `python -c \"import sys; print(sys.path)\"`\n    - Try manual environment entry: `nix develop`\n\n### Files You Can Safely Modify\n\n- `~/.env` - Your personal environment variables (create as needed)\n- `mounts.nix` - Network storage mounts (remove or customize for your setup)\n- `system-packages.nix` - System-wide packages\n- `wallpapers/` - Add your own wallpapers here\n- `theme/theme.nix` - Customise colours and styling\n- Any configuration in `home/` - Tweak application settings\n- `dev-templates/` - Add your own development environment templates\n- Project-specific `flake.nix` files - Customize development environments per project\n\n### Files You Should Be Careful With\n\n- `hardware-configuration.nix` - Generated by NixOS, specific to your hardware\n- `flake.lock` - Manages dependency versions, let Nix handle this\n\n---\n\n## 📸 A Glimpse of the Desktop\n\n![A clean desktop layout showing a terminal, a status bar, and a code editor, all consistently themed.](./screenshots/hyprland-layout.png)\n\n---\n\n## 🎯 Key Features \u0026 Topics\n\nThis NixOS configuration showcases:\n\n### Core Technologies\n- **Declarative System Management** - NixOS with flakes for reproducible builds\n- **Modern Window Manager** - Hyprland Wayland compositor with advanced features\n- **Home Manager Integration** - Comprehensive dotfiles and user configuration management\n- **Mixed Package Sources** - Stable and unstable channel support for latest software\n\n### Desktop Environment Features\n- **Wayland-Native Tools** - Modern alternatives: Waybar, Mako notifications, Wofi launcher\n- **Consistent Theming** - Centralised colour scheme across all applications\n- **Keyboard-Driven Workflow** - Optimised for productivity and minimal mouse usage\n- **Gaming Ready** - Steam, ProtonUp-Qt, and performance optimisations included\n\n### Developer-Friendly (Phase 2 Architecture)\n- **Project-Specific Development Environments** - Isolated, reproducible environments using Nix flakes\n- **Automatic Environment Switching** - Direnv integration for seamless project transitions\n- **80% Faster System Rebuilds** - Development packages moved to project-level flakes\n- **Zero Dependency Conflicts** - Each project has its own package versions\n- **VSCode Integration** - Automatic environment detection with direnv extension\n- **Template System** - Pre-configured environments for Python ML/web, Node.js, and custom setups\n- **Comprehensive Documentation** - Inline comments explaining NixOS patterns and quirks\n- **Modular Architecture** - Easy to understand, modify, and extend configuration\n- **Secret Management** - Secure handling of API keys and sensitive configuration\n- **Build Optimization** - Binary cache configuration for faster rebuilds\n- **Automatic Maintenance** - Weekly garbage collection and daily system updates keep the system clean and current\n\nPerfect for developers, Linux enthusiasts, and anyone interested in modern declarative system configuration with Wayland desktop environments.\n\n### GitHub Topics\n`nixos` `hyprland` `wayland` `flakes` `home-manager` `catppuccin` `catppuccin-mocha` `linux-desktop` `dotfiles` `declarative-configuration` `wayland-compositor` `nix-flakes` `desktop-environment` `linux-customisation` `system-configuration` `waybar` `kitty-terminal` `developer-tools` `direnv` `development-environment` `reproducible-builds` `project-templates` `python-development` `nodejs-development`\n\n---\n\n## 🙏 Acknowledgements\n\nThis configuration wouldn't exist without the incredible work and documentation from the community. Huge thanks to:\n- The [NixOS Wiki](https://nixos.wiki/) and its contributors\n- The [Hyprland Wiki](https://wiki.hyprland.org/)\n- The passionate NixOS, Hyprland, and Linux communities on Reddit, Discord, and beyond.\n\n---\n\n## 📜 Licence\n\nThis configuration is released under the [MIT Licence](./LICENSE). Feel free to fork, adapt, and learn from it, but please do so at your own risk!\n\n\u003cdiv align=\"center\"\u003e\n\n**Happy Hacking!**\n\n\u003c/div\u003e","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flawrab%2Fnixos-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flawrab%2Fnixos-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flawrab%2Fnixos-config/lists"}