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

NixOS Steam Dual Boot Implementation Plan

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

Architectural Overview

The Problem with Traditional 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

Separate Libraries:

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

Our Solution: Asymmetric Symlink Architecture

Windows Steam → NTFS Shared Library (real files, primary storage)
                        ↑
Linux Steam → ext4 Library (symlinks) ──┘

Key Insight: Make Linux the "smart" side that handles complexity, while Windows gets simple, reliable access to real files.

Architecture Deep Dive

Component 1: NTFS Shared Library

Purpose: Primary storage for all game files, designed for Windows Steam

• Location: /mnt/shared-steam (mounted NTFS partition)
• Ownership: Windows Steam has native, unrestricted access
• Contents: Real game files, installed/updated by Windows Steam

Why this satisfies our goals:

• ✅ Windows stability: Native NTFS access, no drivers or special handling
• ✅ Performance: No filesystem translation layer for Windows
• ✅ Reliability: Windows Steam operates in its natural environment

Component 2: Linux Native Library

Purpose: Linux Steam's working directory with intelligent file management

• Location: /home/user/.local/share/Steam/steamapps (ext4/btrfs)
• Contents: Symlinks to shared library + Linux-specific metadata
• Management: Automated script maintains symlink consistency

Why this satisfies our goals:

• ✅ Eliminate storage waste: Symlinks use negligible space
• ✅ Linux performance: Native filesystem for Steam client data
• ✅ Graceful degradation: Linux games still work if shared library fails

Component 3: Intelligent Deduplication Script

Purpose: Automatically manage game installations and eliminate duplicates

Core Logic:

# Scenario 1: New Windows install
if [[ -d "$shared_path" && ! -e "$linux_path" ]]; then
    ln -s "$shared_path" "$linux_path"  # Link to Windows install
fi

# Scenario 2: Linux install exists, no Windows version
if [[ -d "$linux_path" && ! -L "$linux_path" && ! -d "$shared_path" ]]; then
    mv "$linux_path" "$shared_path"    # Move to shared storage
    ln -s "$shared_path" "$linux_path" # Replace with symlink
fi

# Scenario 3: Both exist (duplicate install)
if [[ -d "$linux_path" && ! -L "$linux_path" && -d "$shared_path" ]]; then
    # Intelligent merge: keep larger/newer, discard duplicate
    deduplicate_installation "$game_name"
fi

Why this satisfies our goals:

• ✅ Minimize maintenance: Fully automated, runs on boot/schedule
• ✅ Eliminate waste: Automatically consolidates duplicate installs
• ✅ Seamless access: New games appear on both OSes transparently

Component 4: NTFS Mount Configuration

Purpose: Secure, performant NTFS access with proper permissions

fileSystems."/mnt/shared-steam" = {
  device = "/dev/disk/by-uuid/YOUR-NTFS-UUID";
  fsType = "ntfs-3g";
  options = [ 
    "uid=1000"          # Your user owns all files
    "gid=100"           # Users group
    "umask=022"         # Secure but usable permissions
    "dmask=022"         # Directory permissions: 755
    "fmask=133"         # File permissions: 644 + executable
    "windows_names"     # Handle Windows naming conventions
    "big_writes"        # Performance optimization
    "user_xattr"        # Extended attributes for compatibility
  ];
};

Why this satisfies our goals:

• ✅ Eliminate permission issues: Consistent ownership and permissions
• ✅ Performance: Optimized mount options for gaming workloads
• ✅ Reliability: Stable, well-tested NTFS-3G configuration

Implementation Strategy

Phase 1: Base Setup

1. Partition Management:

   • Identify/create NTFS partition for shared library
   • Ensure sufficient space (recommend 1TB+ for modern libraries)

2. NixOS Configuration:

   • Add NTFS mount with optimized options
   • Enable Steam with proper permissions
   • Configure automatic script execution

3. Initial Testing:

   • Install test game on Windows
   • Verify Linux can access via symlink
   • Confirm updates work from both sides

Phase 2: Script Development

1. Core Deduplication Logic:

   • Game discovery and inventory
   • Symlink management
   • Conflict resolution

2. Safety Features:

   • Permission verification
   • Backup creation before major operations
   • Rollback capability

3. Automation Integration:

   • SystemD service for boot-time execution
   • Optional inotify-based real-time updates

Phase 3: Optimization

1. Performance Tuning:

   • I/O scheduler optimization for gaming workloads
   • NTFS mount parameter fine-tuning
   • Script performance optimization

2. Robustness Improvements:

   • Error handling and recovery
   • Logging and monitoring
   • Edge case handling

Trade-offs and Considerations

Advantages

Storage Efficiency:

• ✅ Single copy of each game (terabytes saved)
• ✅ Symlinks use negligible space
• ✅ No artificial storage constraints

Maintenance:

• ✅ Fully automated after initial setup
• ✅ Self-healing: script fixes broken symlinks
• ✅ No manual intervention required

Compatibility:

• ✅ Windows Steam operates normally
• ✅ Linux Steam gets full game access
• ✅ Updates from either OS benefit both

Limitations

Complexity:

• ⚠️ More complex than separate libraries
• ⚠️ Requires custom script maintenance
• ⚠️ NixOS-specific configuration

Dependencies:

• ⚠️ Relies on NTFS-3G stability
• ⚠️ Script must run reliably
• ⚠️ NTFS partition must remain healthy

Edge Cases:

• ⚠️ Some games may have platform-specific files
• ⚠️ Very large libraries may stress script performance
• ⚠️ Symlink chains could confuse some games

Risk Mitigation

Backup Strategy:

• Regular snapshots of shared library
• Script creates backups before major operations
• Steam's built-in backup/restore as fallback

Fallback Options:

• Linux can install games locally if shared library fails
• Windows operates independently
• Script can be disabled without breaking either Steam installation

Monitoring:

• Log all script operations
• SystemD service status monitoring
• Disk space monitoring for both partitions

Expected Outcomes

Immediate Benefits

• 50-80% storage savings (typical for large game libraries)
• Zero maintenance after initial setup
• Identical game performance on both platforms

Long-term Benefits

• Simplified game management: Install once, play anywhere
• Faster OS switching: No need to reinstall games when switching primary OS
• Future extensibility: Foundation for more advanced features (save sync, etc.)

Success Metrics

• ✅ Games launch successfully from both OSes
• ✅ Updates from either OS work correctly
• ✅ No manual intervention required for normal operation
• ✅ Storage usage comparable to single-OS setup
• ✅ No performance degradation compared to native installs

Implementation Files Needed

1. NixOS Configuration Module (steam-dual-boot.nix)
2. Deduplication Script (steam-dedupe.sh)
3. SystemD Service Definition (steam-linker.service)
4. Installation Instructions (SETUP.md)
5. Troubleshooting Guide (TROUBLESHOOTING.md)

This architecture provides a robust, maintainable solution that maximizes storage efficiency while preserving the stability and performance requirements of both operating systems.