Zero-Configuration NixOS Guide

This template now provides zero-configuration hardware optimization that automatically detects and optimizes your system without manual tuning.

Overview

The NixOS template includes intelligent systems that eliminate manual configuration:

Quick Start

Enable Auto-Optimization

Add this single line to any configuration to enable zero-configuration optimization:

hardware.autoOptimization.enable = true;

That’s it! Your system will automatically:

Verify It’s Working

After enabling, you can check what was detected:

# Quick hardware summary
hw-info

# Detailed detection results (with debug = true)
hardware-detection-info

Template Integration

All template configurations can benefit from auto-optimization:

Desktop/Workstation Templates

# hosts/desktop-template/configuration.nix
{
  imports = [ /* standard imports */ ];

  # Enable zero-configuration optimization
  hardware.autoOptimization.enable = true;

  # Rest of your configuration...
}

Result: Automatically optimized for high-performance desktop use with appropriate GPU drivers and performance settings.

Laptop Templates

# hosts/laptop-template/configuration.nix
{
  imports = [ /* standard imports */ ];

  # Enable with laptop-aware optimizations
  hardware.autoOptimization = {
    enable = true;
    debug = true;  # Enable battery monitoring commands
  };
}

Result: Automatically enables power management, TLP, thermal management, and battery-optimized settings.

Server Templates

# hosts/server-template/configuration.nix
{
  imports = [ /* standard imports */ ];

  # Server optimization with performance focus
  hardware.autoOptimization = {
    enable = true;
    detection = {
      enablePlatformOptimization = false;  # Skip laptop power-saving
    };
  };
}

Result: Optimized for server workloads with appropriate kernel, memory management, and build parallelism.

Hardware-Specific Examples

High-Performance Gaming Rig

Detected: 32GB RAM, 16 CPU cores, NVIDIA RTX GPU, NVMe SSD

Automatic Optimization:

Developer Laptop

Detected: 16GB RAM, 8 CPU cores, Intel GPU, SSD, Battery

Automatic Optimization:

Home Server

Detected: 8GB RAM, 4 CPU cores, No GPU, HDD

Automatic Optimization:

Advanced Configuration

Override Detection

When hardware detection is incorrect:

hardware.autoOptimization = {
  enable = true;
  override = {
    memoryGB = 32;        # Force high-memory optimizations
    cpuCores = 16;        # Force high-performance CPU settings
    hasNvidiaGPU = true;  # Force NVIDIA drivers even if not detected
    hasSSD = true;        # Force SSD optimizations
    isLaptop = false;     # Force desktop optimization
  };
};

Selective Optimization

Enable only specific optimization categories:

hardware.autoOptimization = {
  enable = true;
  detection = {
    enableMemoryOptimization = true;   # ZRAM, swappiness optimization
    enableCpuOptimization = true;      # Governor, kernel, build settings
    enableGpuOptimization = false;     # Skip GPU detection/drivers
    enableStorageOptimization = true;  # I/O scheduler optimization
    enablePlatformOptimization = true; # Laptop vs desktop differences
  };
};

Debug Mode

Enable detailed hardware detection information:

hardware.autoOptimization = {
  enable = true;
  debug = true;  # Enables hardware-detection-info command
};

Integration with Existing Modules

Auto-optimization works alongside existing template modules:

With Power Management

modules = {
  # Manual power management (takes precedence)
  hardware.power-management = {
    enable = true;
    cpuGovernor = "ondemand";  # This overrides auto-detection
  };

  # Auto-optimization (supplements manual settings)
  hardware.autoOptimization = {
    enable = true;
    detection = {
      enableCpuOptimization = false;  # Don't override manual governor
      enableMemoryOptimization = true;  # Still optimize memory
    };
  };
};

With Gaming Module

modules = {
  gaming.steam.enable = true;

  hardware.autoOptimization.enable = true;
  # Result: Automatically detects gaming hardware and optimizes for:
  # - Maximum CPU performance
  # - GPU hardware acceleration
  # - Low-latency memory management
  # - Fast SSD game loading
};

Troubleshooting

Hardware Not Detected

  1. Check detection results:

    hardware-detection-info

  2. Override incorrect detection:

    hardware.autoOptimization.override.hasNvidiaGPU = true;

Configuration Conflicts

If auto-optimization conflicts with manual settings:

# Disable conflicting optimizations
hardware.autoOptimization.detection.enableCpuOptimization = false;

Manual settings always take precedence over auto-optimization defaults.

Performance Issues

For performance-critical systems:

hardware.autoOptimization.override = {
  memoryGB = 64;  # Force high-memory optimizations
  cpuCores = 32;  # Force high-performance settings
  isLaptop = false;  # Skip power-saving optimizations
};

Migration from Manual Configuration

Before (Manual Configuration)

# Manual hardware configuration
zramSwap.enable = true;
zramSwap.memoryPercent = 25;
powerManagement.cpuFreqGovernor = "performance";
hardware.graphics.enable = true;
services.xserver.videoDrivers = ["nvidia"];
boot.kernelParams = ["transparent_hugepage=madvise"];
nix.settings.cores = 8;
# ... dozens more manual settings

After (Zero Configuration)

# Automatic hardware optimization
hardware.autoOptimization.enable = true;
# That's it! All the above settings applied automatically based on detected hardware

Benefits Summary

The zero-configuration approach makes NixOS accessible to users without deep hardware knowledge while maintaining the flexibility that power users expect.

See Also