Cairn

A modular NixOS framework and library for building reproducible systems with Home Manager, modern desktop environments, and curated development tools.

Maximized windows, no borders, no distractions — designed for focused work

What is Cairn?

Cairn is a NixOS framework and library that you import into your own flake to build NixOS configurations. Think of it as a curated collection of modules, packages, and home-manager configs that work together.

You maintain just a few simple files (~30 lines), and cairn provides everything else: desktop environment, development tools, system configuration, and more.

Quick Start

Prerequisites: A running NixOS system (UEFI boot, BIOS/MBR not supported)

If you haven't installed NixOS yet, download the graphical installer from nixos.org/download — it provides a familiar desktop environment that makes partitioning and installation straightforward. Boot in UEFI mode, complete the install, then return here.

Fresh NixOS Install

bash <(curl -sL https://raw.githubusercontent.com/kcalvelli/cairn/master/scripts/install.sh)

This handles everything: enables flakes, configures binary caches, and launches the interactive installer.

Flakes Already Enabled

nix run --refresh github:kcalvelli/cairn#init

The installer offers three modes: scripted setup, add a host to an existing Cairn config, or AI-assisted configuration with Claude Code.

After your first rebuild, you may need to reconnect to WiFi — Cairn switches the WiFi backend to iwd, which requires re-entering your network password once.

See docs/INSTALLATION.md for complete instructions.

Features

Home Profiles

Cairn supports per-user desktop profiles on multi-user systems. Each user's profile is set independently via homeProfile in their users/<name>.nix config:

Profile	Experience	Target User
standard	Keyboard-driven tiling workflow with AI tools, developer launchers, and borderless maximized windows	Power users, developers
normie	Mouse-driven ChromeOS-like desktop with window titlebars, DMS taskbar/app launcher, and minimal keybindings	Non-technical users

Both profiles share: Visual theming (Colloid + matugen), wallpapers, PWA catalog (30+ apps), media playback, Flatpak support, and MIME associations.

Key differences in normie profile:

• Window titlebars with close/minimize/maximize controls (client-side decorations)
• Only 3 keyboard shortcuts: Mod+Q (close), Mod+F (maximize), Print (screenshot)
• DMS provides taskbar, app launcher, and window switching — no tiling concepts exposed
• No AI tools, developer launchers, dropdown terminal, or keybinding reference at startup

# users/alice.nix — per-user profile override
{ ... }:
{
  cairn.users.users.alice = {
    fullName = "Alice Smith";
    email = "alice@example.com";
    homeProfile = "normie";  # or "standard" (default)
  };
}

Desktop Experience

• Niri compositor - Scrollable tiling Wayland compositor with workspace overview
• DankMaterialShell - Material design shell with:
  • System monitoring widgets (CPU, RAM, disk usage)
  • Clipboard history management (cliphist)
  • VPN status widget
  • Brightness controls (screen & keyboard)
  • Color picker and dynamic theming (matugen)
  • Audio visualizer (cava)
  • Calendar integration (khal)
  • Built-in polkit agent
• Idle management - Automatic screen power-off after 30 minutes (configurable)
• Curated wallpaper collection - 18 high-quality wallpapers auto-deployed to ~/Pictures/Wallpapers
  • Automatic updates when collection changes
  • Random wallpaper selection on first run and collection updates
  • Enable in your user.nix: add cairn.wallpapers.enable = true; under home-manager.users.${username}
  • Optional: Set cairn.wallpapers.autoUpdate = false; to disable auto-randomization
• Wallpaper blur effects - Automatic blur for overview mode
• Ghostty terminal - Modern GPU-accelerated terminal with dropdown mode
• GPU Hardware Acceleration - Automatic browser acceleration based on GPU type:
  • AMD: VA-API video decode/encode with modern Chrome 131+ flags
  • NVIDIA: VA-API via nvidia-vaapi-driver with optimized environment variables
  • Accelerates: Video playback, WebGL, Canvas rendering, GPU rasterization
  • Brave stable is enabled by default; Brave Nightly/Beta/Origin and Chrome are opt-in via desktop.browsers.<name>.enable and pick up the same GPU-aware flags when enabled.
• Syncthing XDG sync - Peer-to-peer file sync across hosts via Tailscale (Documents, Music, Pictures, etc.)

Development

• Multi-language environments - Rust, Zig, Python, Node.js
• DevShells - Project-specific toolchains via nix develop
• LSP support - Language servers pre-configured
• Development tools - Organized by category

Infrastructure

• Declarative disks - Disko templates for automated provisioning
• Secure boot - Lanzaboote support
• Virtualization - libvirt, QEMU, Podman
• Hardware optimization - Automatic desktop/laptop configuration
• Modular architecture - Enable only what you need
• Self-hosted services - Caddy + Tailscale HTTPS, Immich photo backup

Screenshots

Workspace Overview with Blur Effect

Niri's scrollable workspace view showing multiple contexts (VS Code, Dolphin, terminals) with automatic wallpaper blur and built-in keybinding reference

Dropdown Terminal (Super+`)

Instant terminal overlay (97% width, 420px tall) for quick commands during focused work — nix build running over VS Code

Strategic Floating Windows

Supporting tools that don't disrupt focus: Qalculate calculator (floating), Dolphin file manager, and split-screen tiling with Brave browser and VS Code

DMS Material Design Shell

DankMaterialShell with system monitor, settings panel, and Material Design widgets — showing user profile, network status, and performance graphs

Documentation

📖 Complete Documentation Hub - Start here for comprehensive guides

Quick Links:

• Installation Guide - Step-by-step setup
• Application Catalog - See what's included
• Library API Reference - Using cairn.lib.mkSystem
• Adding Multiple Hosts - Multi-host setups

Library API

Cairn exports cairn.lib.mkSystem for building NixOS configurations with minimal code:

nixosConfigurations.myhost = cairn.lib.mkSystem {
  hostname = "myhost";
  formFactor = "desktop";  # or "laptop"
  hardware = { cpu = "amd"; gpu = "amd"; };
  modules = { desktop = true; development = true; };
  users = [ "alice" ];            # References users/alice.nix
  configDir = self.outPath;       # Required when users is non-empty
  hardwareConfigPath = ./hardware.nix;
};

See docs/LIBRARY_USAGE.md for complete API documentation and all available options.

Examples

Check out these example configurations:

• examples/example-config - Multi-host setup with multiple users

What's Included

• Desktop: Niri compositor with scrollable tiling, DankMaterialShell with widgets, Ghostty terminal, GPU-accelerated browsers (AMD/NVIDIA), idle management
• Development: Rust, Zig, Python, Node.js toolchains with LSP support
• Applications: Curated set of productivity, media, and development tools — see Application Catalog
• PWAs: Progressive Web Apps integrated as native applications
• Virtualization: libvirt, QEMU, Podman support (optional)
• Gaming: Steam, GameMode, Proton (optional)
• AI Services (optional, fully opt-in):
  • Cloud agents behind explicit per-vendor flags — services.ai.claude.enable, services.ai.gemini.enable, services.ai.openai.enable. Setting services.ai.enable = true alone only installs whisper-cpp; you opt into the agents you actually use.
  • Workflow tooling (openspec, spec-kit) gated behind services.ai.workflow.enable.
  • Local LLM (services.ai.local.enable): llama.cpp's llama-server with ROCm/CUDA acceleration, single GGUF model file, server/client roles wired through Tailscale Services so a beefy desktop can serve a thin laptop.
  • MCP server integration with on-demand discovery via the mcp-gw CLI (99% token reduction vs. loading every tool schema upfront).
• Companion (optional): cairn-companion as a first-class module — persistent persona memory synced via Syncthing, daemon + CLI + TUI auto-wired for standard-profile users (modules.companion = true).
• Self-Hosted Services: Caddy reverse proxy with Tailscale HTTPS, Immich photo backup (optional)

See project structure and module details in docs/README.md

Installing Additional Applications

Flatpak via Flathub (Recommended) 📦

Cairn ships with Flathub pre-configured and a built-in one-click installer. Visit flathub.org, click "Install" on any app, and a terminal window opens showing the installation progress.

Why Flathub?

• ✅ Sandboxed applications — Better security isolation
• ✅ Latest versions — Apps update independently of NixOS
• ✅ One-click install — Click "Install" on flathub.org, confirm in terminal
• ✅ Large ecosystem — Thousands of desktop applications
• ✅ Theme integration — Apps automatically use your GTK theme
• ✅ No system rebuilds — Install/remove apps instantly

To install apps:

1. Visit flathub.org in your browser
2. Find an app and click Install
3. A small terminal window opens — confirm with y and watch it install

You can also manage installed Flatpaks with Warehouse (included).

Declarative NixOS Packages

For system-level tools or reproducible setups, add packages to extraConfig in your host configuration:

extraConfig = {
  environment.systemPackages = with pkgs; [
    firefox
    inkscape  # Apps removed from defaults are still available
    # your packages here
  ];
};

When to use NixOS packages instead of Flathub:

• System services and CLI tools (not desktop apps)
• Reproducible builds across multiple machines
• Packages that integrate deeply with the system

Note: Most desktop applications work well as Flatpaks due to sandboxing and independent updates. Reserve NixOS packages for system-level tools, command-line utilities, and development environments.

Why Cairn?

• ✅ Minimal maintenance - Your config is ~30 lines, cairn handles the rest
• ✅ Selective updates - nix flake update to get new features when you want
• ✅ Version pinning - Lock to specific cairn versions for stability
• ✅ Clear separation - Your personal configs vs framework code
• ✅ Easy sharing - Your config repo is simple and understandable
• ✅ Community framework - Benefit from improvements and updates
• ✅ Library design - Not a personal config - no hardcoded regional defaults

Workflow Philosophy (Standard Profile)

The standard home profile is built around a focused, distraction-free workflow optimized for single-monitor productivity. (The normie profile replaces this with a mouse-driven, ChromeOS-like experience — see Home Profiles.)

Maximized Windows by Default

• All applications open maximized to keep your attention on the task at hand
• Web browsers, code editors, terminals, and productivity apps fill the screen
• Reduces context switching and visual clutter
• Window borders are disabled for a seamless, immersive experience

Strategic Floating Windows

• Utility apps that support your work open floating:
  • Qalculate (quick calculations during work)
  • Dolphin file manager (1200×900, for quick file operations)
  • Google Messages PWA (500×700, pinned top-left for quick replies)
  • DankMaterialShell settings (configuration without disruption)
  • Brave Picture-in-Picture (for background media)
• These apps are intentionally kept small and out-of-the-way

Dropdown Terminal (Super+`)

• Instant access to a terminal overlay (97% screen width, 420px tall)
• Perfect for quick commands while working:
  • Git operations during code review
  • Running builds without leaving your editor
  • System checks and monitoring
  • Command-line tools during development
• Press Super+` again to dismiss and return to focused work

Scrolling Workspace Navigation

• Niri's scrollable tiling compositor lets you organize work by project or context
• Each workspace holds maximized windows for different projects
• Scroll through workspaces (Mod+Wheel) to switch between contexts seamlessly
• Each context remains focused and distraction-free when you return to it

Single-Monitor Optimized

• The entire workflow is designed and tested for single-monitor setups
• Multi-monitor configurations are not tested and may not work as expected
• This deliberate constraint encourages focused work over sprawling layouts

This workflow prioritizes deep work over multitasking, with every design decision aimed at keeping you focused on one task at a time while maintaining quick access to supporting tools.

Library Philosophy

Cairn is designed as a framework/library, not a personal configuration:

• No regional defaults - You must explicitly set timezone and locale (no assumptions about your location)
• No hardcoded preferences - Personal choices belong in your config, not the framework
• Modular by design - Enable only what you need, customize everything
• Multi-user ready - Per-user home profiles (standard/normie) for diverse users on shared systems

This means some options are required (like cairn.system.timeZone) to force explicit configuration rather than assuming defaults that might not fit your use case.

Contributing

Contributions welcome! This is a public framework meant to be used by others.

• Report issues for bugs or missing features
• Submit PRs for improvements
• Share your configurations using cairn
• Improve documentation

Acknowledgments

Built with and inspired by:

• NixOS and the nix-community
• Home Manager
• Niri compositor
• DankMaterialShell
• Countless community configurations and blog posts

License

MIT License. See LICENSE for details.