nixos-configs/nixos-steam-dual-boot-plan.md

NixOS Steam Dual Boot Implementation Plan (Btrfs + Beesd Edition)

Goals & Motivations

Primary Goals

1. Eliminate storage waste: Avoid duplicating terabytes of Steam games across Windows and NixOS
2. Minimize maintenance overhead: Create a solution that works reliably without constant tweaking
3. Preserve Windows stability: Ensure Windows Steam functionality remains unaffected by the dual-boot setup
4. Maintain gaming performance: No significant performance degradation on either OS

Secondary Goals

• Seamless game access: Games should be available on both OSes without manual intervention
• Update compatibility: Game updates from either OS should be usable by both
• Future-proof architecture: Solution should be extensible and maintainable
• Multi-user support: Handle 3 Windows users sharing libraries, with 1 user also using Linux

Architectural Overview

The Problem with Previous Approaches

Shared NTFS Library (Traditional):

• ❌ Proton creates files with colons, corrupting NTFS
• ❌ Requires fragile symlinks that Windows can break
• ❌ Permission issues plague the setup
• ❌ Valve officially discourages this approach

Complex Symlink Management:

• ❌ Requires custom scripts and maintenance
• ❌ Fragile edge cases with Steam updates
• ❌ Potential compatibility issues with Proton and anti-cheat

Separate Libraries:

• ❌ Wastes terabytes of storage
• ❌ Games must be installed twice
• ❌ No benefit from either OS's installations

Our Solution: Btrfs + Beesd Automatic Deduplication

Windows Steam → /steam/windows/ (btrfs via WinBtrfs driver)
                     ↓
Linux Steam   → /steam/linux/  (native btrfs)
                     ↓
               [beesd automatically deduplicates identical files]

Key Insight: Let each Steam installation work independently, rely on proven btrfs deduplication technology to eliminate duplicate storage automatically.

Architecture Deep Dive

Component 1: Shared Btrfs Filesystem

Purpose: Single high-performance filesystem for all game storage

• Location: /steam (dedicated btrfs partition)
• Contents:
  • /steam/windows/ - Windows Steam library
  • /steam/linux/ - Linux Steam library
• Access: Native on Linux, WinBtrfs driver on Windows

Why this satisfies our goals:

• ✅ Automatic deduplication: Beesd handles duplicate elimination transparently
• ✅ No maintenance: Zero custom scripts or symlink management
• ✅ Independent operation: Each Steam installation works normally
• ✅ Performance: Optimized mount options for gaming workloads

Component 2: Beesd Deduplication Service

Purpose: Automatic background deduplication of game files

Core Functionality:

• Continuously scans /steam for duplicate blocks
• Automatically deduplicates identical files between /steam/windows/ and /steam/linux/
• Operates transparently - games never know deduplication is happening
• Handles common duplicates: DirectX runtimes, Visual C++ redistributables, game engines, shared assets

Expected Efficiency:

• 40-70% storage savings for typical game libraries
• Common targets: Unity/Unreal engine files, shared libraries, identical texture assets
• Real-time operation: New duplicates eliminated automatically

Component 3: WinBtrfs Driver Integration

Purpose: Provide Windows with native btrfs read/write access

# No special configuration needed - standard btrfs mount
fileSystems."/steam" = {
  device = "/dev/disk/by-uuid/YOUR-BTRFS-UUID";
  fsType = "btrfs";
  options = [ 
    "noatime"    # Don't update access times - major gaming performance boost
    "ssd"        # SSD optimizations
  ];
};

Windows Requirements:

• Install WinBtrfs driver (https://github.com/maharmstone/btrfs)
• Configure Steam library path to point to /steam/windows/
• No special configuration needed - works like any other drive

Component 4: Beesd Configuration

Purpose: Optimized deduplication for gaming workloads

services.beesd.filesystems = {
  steam = {
    spec = "/steam";
    hashTableSizeMB = 512;   # Sized for ~4TB of game data (128MB per TB)
    verbosity = "err";       # Only show actual problems
  };
};

Hash Table Storage:

• Stored as file: /steam/.beeshash
• 512MB handles up to 4TB of game data efficiently (beesd recommends 128MB per TB)
• Loaded into RAM on-demand, not all resident simultaneously
• Smaller hash table = better performance and less disk usage

Partition Strategy

4-Partition Architecture

1. Windows Boot Partition (NTFS) - Existing

   • Standard Windows system drive
   • Unchanged from current setup

2. Linux Boot Partition (btrfs/ext4) - New

   • NixOS system installation
   • Standard Linux root filesystem

3. Shared Steam Library (btrfs) - New

   • /steam/windows/ - Windows Steam library
   • /steam/linux/ - Linux Steam library
   • Automatic beesd deduplication

4. Legacy Windows Steam (NTFS) - Existing, Optional

   • Keep for anti-cheat games that may not work on btrfs
   • Can be eliminated if all games work on btrfs
   • Provides fallback option during testing

Multi-User Considerations

Current Setup: 3 Windows users sharing Steam libraries Migration Strategy:

• Other Windows users continue using existing NTFS library
• Primary user (johno) experiments with btrfs library
• Easy rollback: point Steam back to NTFS if issues arise
• Gradual migration as confidence builds

Implementation Strategy

Phase 1: Base Setup

1. Partition Creation:

   • Create new btrfs partition for /steam (recommend 2TB+ for modern libraries)
   • Install NixOS on separate Linux boot partition
   • Keep existing Windows partitions untouched

2. NixOS Configuration:

   fileSystems."/steam" = {
     device = "/dev/disk/by-uuid/YOUR-BTRFS-UUID";
     fsType = "btrfs";
     options = [ "noatime" "ssd" ];
   };
   
   services.beesd.filesystems = {
     steam = {
       spec = "/steam";
       hashTableSizeMB = 512;   # 128MB per TB recommended
       verbosity = "err";
     };
   };
   

3. Windows Setup:

   • Install WinBtrfs driver
   • Add Steam library pointing to /steam/windows/
   • Test with a few small games initially

Phase 2: Gradual Migration

1. Safe Game Testing:

   • Start with single-player games
   • Test save game compatibility
   • Verify performance matches NTFS installation

2. Anti-Cheat Evaluation:

   • Test multiplayer games progressively
   • Document which games work on btrfs vs require NTFS
   • Keep problematic games on legacy NTFS partition

3. Deduplication Verification:

   • Monitor beesd logs for successful deduplication
   • Use btrfs filesystem du /steam to verify space savings
   • Benchmark game loading times vs separate installations

Phase 3: Optimization

1. Performance Tuning:

   • Monitor btrfs performance under gaming workloads
   • Adjust mount options if needed
   • Optimize beesd parameters based on actual usage

2. Monitoring Setup:

   • SystemD service monitoring for beesd
   • Disk space alerts for /steam partition
   • Basic health checks for WinBtrfs stability

Trade-offs and Considerations

Advantages

Storage Efficiency:

• ✅ 40-70% storage savings through automatic deduplication
• ✅ No manual intervention required
• ✅ Works with any game installation method

Simplicity:

• ✅ No custom scripts to maintain
• ✅ No symlink complexity
• ✅ Standard Steam library management on both OSes

Reliability:

• ✅ Each Steam installation completely independent
• ✅ Btrfs and beesd are mature, proven technologies
• ✅ Graceful degradation if deduplication fails

Performance:

• ✅ Optimized mount options for gaming
• ✅ No compression overhead
• ✅ Native filesystem performance on both OSes

Limitations

Windows Dependencies:

• ⚠️ Requires WinBtrfs third-party driver
• ⚠️ Driver updates needed with major Windows releases
• ⚠️ Potential compatibility issues with some anti-cheat systems

Complexity Trade-offs:

• ⚠️ More partitions to manage than single-filesystem approach
• ⚠️ Beesd adds background CPU/disk usage (minimal but present)
• ⚠️ Hash table requires disk space (512MB for large libraries)

Platform Compatibility:

• ⚠️ Some games may prefer NTFS for maximum compatibility
• ⚠️ Anti-cheat systems may flag non-NTFS installations
• ⚠️ WinBtrfs stability depends on third-party development

Risk Mitigation

Backup Strategy:

• Regular btrfs snapshots of /steam partition
• Keep legacy NTFS Steam library as fallback
• Steam's built-in backup/restore for critical games

Fallback Options:

• Easy to revert games to NTFS library if needed
• Linux can install games locally if /steam partition fails
• Independent operation means failure in one OS doesn't affect the other

Monitoring:

• SystemD service status for beesd
• Disk space monitoring for early warning
• Game launch testing after major updates

Expected Outcomes

Immediate Benefits

• 40-70% storage savings for typical game libraries
• Zero maintenance after initial setup
• Identical performance to native installations
• Future-proof architecture using standard technologies

Long-term Benefits

• Automatic optimization: New games deduplicated without intervention
• Simplified management: One shared library instead of separate installations
• Technology leverage: Benefits from ongoing btrfs and beesd improvements

Success Metrics

• ✅ Games launch successfully from both OSes
• ✅ Save games work correctly on both platforms
• ✅ Updates from either OS don't break the other
• ✅ Storage usage 40-70% less than separate libraries
• ✅ No performance degradation vs native installations
• ✅ Anti-cheat compatibility acceptable for target games

Monitoring and Maintenance

Automated Monitoring:

# Add to NixOS configuration for basic monitoring
systemd.services.steam-health-check = {
  description = "Check Steam partition and beesd health";
  serviceConfig = {
    Type = "oneshot";
    ExecStart = pkgs.writeScript "steam-health" ''
      #!/bin/bash
      # Check beesd service status
      systemctl is-active beesd-steam >/dev/null || echo "WARN: beesd not running"
      
      # Check disk space
      USAGE=$(df /steam | tail -1 | awk '{print $5}' | sed 's/%//')
      [ "$USAGE" -gt 90 ] && echo "WARN: Steam partition >90% full"
      
      # Verify both directories exist
      [ ! -d "/steam/windows" ] && echo "ERROR: Windows Steam directory missing"
      [ ! -d "/steam/linux" ] && echo "ERROR: Linux Steam directory missing"
    '';
  };
};

systemd.timers.steam-health-check = {
  wantedBy = [ "timers.target" ];
  timerConfig = {
    OnCalendar = "daily";
    Persistent = true;
  };
};

Implementation Files Needed

1. NixOS Configuration Addition - Add to existing machine config
2. WinBtrfs Installation Guide - Windows setup instructions
3. Migration Checklist - Step-by-step game migration process
4. Troubleshooting Guide - Common issues and solutions

This architecture provides maximum storage efficiency with minimal complexity, leveraging proven technologies instead of custom solutions. The automatic nature of btrfs deduplication eliminates the maintenance overhead of complex symlink management while providing excellent storage savings.