kOS

This is my personal NixOS configuration for a clean, keyboard-focused development machine. I built it to keep things simple, consistent, and distraction-free while coding.

demo.mp4

Try Out

# Run the VM demo
nix run github:knoopx/nix

# Or clone and run locally
git clone https://github.com/knoopx/nix
cd nix
nix run path:.

Installation

The unattended installer creates a bootable ISO that automatically installs kOS to the first available disk.

# Build the installer ISO
nix build .#installer-iso

# Write it to a USB drive:
caligula burn result/iso/*.iso

# Or test in a VM first
nix run .#installer-vm-test

⚠️ Warning: The installer will automatically erase and partition the first unused disk it finds. Use with caution.

What I Focus On

• Minimal clutter: Shell has no widgets and apps take the whole vertical space. Keyboard-driven workflow throughout.
• Unified styling: Consistent colors, fonts, and styles across:
  • System GTK/Qt themes and custom Neuwaita icon theme (merged with MoreWaita)
  • Terminal emulator (Kitty)
  • Text editors (VSCode, Helix)
  • Window manager (Niri with custom color schemes)
  • All applications via Stylix theming system
• Reproducible: Everything's declarative, so I can set it up the same way anywhere

Software

Core System

• Niri: A modern, Wayland-native tiling window manager that provides efficient keyboard-driven window management with custom layouts and workspaces
• Firefox: Web browser optimized for privacy with uBlock Origin for ad-blocking, custom search engines, and userstyles for consistent theming. Includes policies for enhanced security and performance thanks to BetterFox and GNOME theme integration
• Chromite: Privacy-focused Chromium fork with enhanced security features
• Kitty: GPU-accelerated terminal emulator with theme integration
• Fish: The user-friendly command line shell with custom completions
• Hyprlock: Screen locker with custom theme
• Yazi: Modern terminal file manager
• Astal: Dynamic shell for desktop widgets and system integration

Development Tools

• VSCode: Primary code editor with custom keybindings, themes, and productivity tools
• Helix: Modal text editor inspired by Vim
• jj (Jujutsu): Version control system with superior history manipulation and workflow management
• jj-hunk: Programmatic hunk selection tool for Jujutsu
• nix-ld: Enables the experience (and caveats) of conventional Linux distros into NixOS, avoiding the need to re-package every single binary

Command Line Tools

• Bat: Cat clone with syntax highlighting
• Btop: Resource monitor
• Delta: Modern diff viewer
• Fzf/Skim: Command-line fuzzy finders
• Nu Shell: Modern shell with structured data processing
• Starship: Customizable prompt

Control Scripts

Custom Nu-based scripts for system control:

• brightness-control: Adjust screen brightness
• display-control: Manage display settings and outputs
• volume-control: Control system and application volume
• media-control: Media playback controls
• session-control: Session management (lock, suspend, logout, etc.)
• window-control: Window management automation
• tablet-mode-control: Toggle tablet mode settings
• voice-input-control: Control voice input services
• recording-indicator: Visual indicator for active recordings
• screen-recording: Screen capture and recording utilities
• google-authenticator-qr-decode: Decode QR codes from Google Authenticator
• pick-project: Project selection utility
• pick-document: Document selection utility

Default Applications

Configured default applications across the system:

• Browser: Firefox ESR
• Terminal: Kitty
• Editor: Helix
• File Manager: Nautilus
• Image Viewer: Eye of GNOME (EOG)
• Video Player: MPV
• Music Player: Decibels

Development Environments

The modules/home-manager/packages/dev/ directory contains language-specific development environments, each providing essential tools for programming in that language:

• Crystal: Compiler, Crystalline language server, Shards package manager, and Mint framework for building web applications
• Go: Compiler, gopls language server, Delve debugger, and build tools for efficient Go development
• JavaScript: Node.js runtime, package managers (Yarn, pnpm), and Bun for modern web development
• Nix: nixpkgs-fmt formatter and development tools for Nix language development
• Nu Shell: Modern shell with plugins for data processing (polars, query, notifications, highlight, skim) and formatting (nufmt)
• Python: Interpreter and development utilities
• Ruby: Interpreter, Bundler for dependency management
• Rust: Compiler and Cargo package manager
• System: C/C++ compilers (GCC, Clang), build tools, and system-level development utilities

Launchers and Extensions

• Vicinae: Application launcher inspired by Raycast
• Astal: Dynamic desktop shell for widgets and system integration
• Camper: Home automation control integration
• Vicinae Extensions: Custom extensions for the launcher

How It's Organized

My Machines

• desktop/: Main workstation featuring:
  • NVIDIA graphics with CUDA support
  • BTRFS filesystem with advanced features
  • Container services (Watchtower for updates, SilverBullet)
  • Hardware acceleration for AI models
  • EasyEffects audio configuration
  • Glance dashboard
• minibookx/: Chuwi Minibook X N150 laptop configuration:
  • Hardware-specific drivers and optimizations
  • Power management and battery optimizations
• vm/: Virtual machine setup for testing with demo scripts
• steamdeck/: Steam Deck configuration with VM test support
• android/: Android Virtual Framework (AVF) image configuration
• live-usb/: Bootable USB configuration for system recovery
• installer/: Unattended installer ISO that automatically partitions and installs kOS:
  • Creates 1GB EFI boot partition + XFS root filesystem
  • Installs complete system with home-manager configuration
  • Auto-reboots after successful installation

Modules

• modules/nixos/: System-level configurations including:
  • defaults/: Global settings for apps, colors, display, fonts, system, and user
  • services/: System services (Plex Media Server, Traefik, Android photo backup, auto-scrcpy, Flatpak, Keyd, etc.)
  • system/: Core system settings (boot, documentation, environment, hardware, networking, Nix configuration, packages, programs, users, virtualisation)
  • theming/: Stylix theming configuration
  • wm/: Window manager and desktop environment settings (Niri, packages, programs, services, XDG)
• modules/home-manager/: User environment configurations:

  • packages/: User packages and development tools

    • dev/: Language-specific development environments (Crystal, Go, JavaScript, Nix, Nu Shell, Python, Ruby, Rust, System)
    • cli.nix: Command-line interface utilities
    • gui.nix: Graphical user interface packages

  • programs/: Application configurations (VSCode, Firefox, Kitty, Fish, Helix, Hyprlock, etc.)

    • firefox/: Firefox with custom policies, profiles, and uBlock rules

    • vicinae/: Vicinae launcher configuration with custom scripts

    • nu-shell/: Nu Shell configuration with custom completions

    • Other programs: bat, btop, chromite, delta, fish, git, helix, hyprlock, jj, kitty, micro, nix-index, pi-ai, skim, starship, voxtype, yazi

  • wm/: Window manager user settings

    • shell.nix: Shell integration with window control
    • niri/: Niri window manager configuration
    • xdg/: XDG desktop integration, GTK themes, dconf settings

Overlays

Package customizations and fixes:

• balatro.nix: Balatro game modifications
• glance.nix: Glance dashboard customizations
• gnome-control-center.nix: GNOME Control Center patches
• pegasus-frontend.nix: Pegasus Frontend modifications
• retroarch.nix: RetroArch emulator customizations
• useless-desktop-items.nix: Desktop item management
• plotly.nix: Plotly library patches
• pi.nix: Pi AI integration

Builders

Helper functions for creating package derivations:

• theming/: Theme builders (MoreWaita icons, Plymouth themes, Stylix Firefox/Gnome themes)

Library

Utility functions for theming, color manipulation, and module loading:

• theming/: Color conversion utilities (hexToRGB, rgbToHex, etc.)
• listNixModulesRecusive.nix: Custom module loading utility

Packages

Custom package definitions in pkgs/:

Control & Utility Scripts:

• brightness-control, display-control, volume-control, media-control
• session-control, window-control, tablet-mode-control
• voice-input-control, recording-indicator, screen-recording
• google-authenticator-qr-decode
• pick-project, pick-document

Applications:

• Neuwaita Icon Theme: Custom icon theme

• NFO Viewer: NFO file viewer

• browser: Custom Firefox/Chromium browser wrapper

• file-manager: Custom file manager wrapper

• image-viewer: Custom image viewer wrapper

• terminal: Custom terminal emulator wrapper

• editor: Custom editor wrapper

• cromite: Privacy-focused Chromium fork

• tts: Text-to-speech utilities

Development & Productivity:

• codemapper: Code mapping and navigation tool
• jj-hunk: Programmatic hunk selection for Jujutsu
• romie: ROM management utility
• sem: Semantic versioning tool
• mdtt: Markdown to text tool
• wacli: WhatsApp CLI client
• gogcli: GOG.com CLI client
• pi-project: Pi AI project integration

Host-Specific Configurations

• home/: User-specific Home Manager configurations
• flake.nix: Main flake with inputs, outputs, and system configurations
• flake.lock: Dependency lock file for reproducible builds