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**:
```bash
# 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

```nix
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.