nixos-configs/STEAM_DECK_JOVIAN_SETUP.md

Steam Deck (nix-deck) Jovian-NixOS Setup Guide

This document describes the setup for installing and maintaining NixOS with Jovian-NixOS on a Steam Deck.

Overview

The nix-deck configuration provides:

• Jovian-NixOS integration for Steam Deck hardware support
• Remote building using zix790prors as the build host
• SteamOS role for easy Steam Deck UI configuration
• Compatibility shim for using Jovian on NixOS 25.05 stable

Architecture

Remote Building

The setup uses distributed builds to avoid slow compilation on the Steam Deck:

• Build Host: zix790prors (powerful desktop)

  • Runs as a dedicated nix-builder user (not root)
  • Accepts SSH connections from client machines
  • Performs all heavy compilation work

• Build Clients: nix-book and nix-deck

  • Automatically offload builds to zix790prors
  • Fall back to local building if remote builder is unavailable
  • Steam Deck heavily prefers remote (speedFactor=4)

Jovian-NixOS Integration

• Jovian module: Provides Steam Deck hardware support, drivers, and Steam UI

• Compatibility layer: roles/jovian-compat.nix provides services.logind.settings for NixOS 25.05

  • IMPORTANT: Remove this when upgrading to NixOS 25.11+
  • An assertion will fail the build if used on 25.11+

• SteamOS role: roles.desktop.steamos abstracts Jovian configuration

  roles.desktop.steamos = {
    enable = true;
    autoStart = false;  # Set to true to boot directly to Steam UI
    desktopSession = "plasmawayland";
  };
  

Initial Installation

Prerequisites

1. Steam Deck in recovery mode or booted to a live Linux environment
2. SSH access enabled on the Steam Deck
3. SSH key set up for passwordless authentication

Option 1: Using nixos-anywhere (Initial Install Only)

# From your main machine
nix run github:nix-community/nixos-anywhere -- \
  --flake .#nix-deck \
  root@<steam-deck-ip>

Note: This is only for the initial install. For updates, see below.

Option 2: Manual Installation

1. Boot Steam Deck from NixOS installer USB
2. Partition and format the disk
3. Mount filesystems
4. Clone this repository
5. Generate hardware config:

   nixos-generate-config --show-hardware-config > /tmp/hw.nix
   

6. Copy the hardware config content to machines/nix-deck/hardware-configuration.nix
7. Keep the jovian.devices.steamdeck settings in the file
8. Install:

   nixos-install --flake .#nix-deck
   

Updates and Rebuilds

Method 1: Remote Build and Deploy (Recommended)

Build on your main machine, deploy to Steam Deck:

# From nix-book or zix790prors
nixos-rebuild switch \
  --flake .#nix-deck \
  --target-host root@nix-deck \
  --build-host localhost

Method 2: On-Device Rebuild (Uses Remote Builder)

The Steam Deck is configured to automatically use zix790prors as a remote builder:

# SSH into the Steam Deck
ssh root@nix-deck

# This will automatically build on zix790prors
nixos-rebuild switch --flake /path/to/nixos-configs#nix-deck

The build will automatically happen on zix790prors and be deployed locally.

Remote Builder Setup

On the Build Host (zix790prors)

The configuration creates a nix-builder user that client machines connect to:

roles.remote-build.enableBuilder = true;

On Client Machines (nix-book, nix-deck)

Configure the remote builder:

roles.remote-build.builders = [{
  hostName = "zix790prors";
  maxJobs = 16;
  speedFactor = 4;  # Higher = prefer remote more
}];

SSH Key Setup

1. Generate SSH key on the builder host for the nix-builder user:

   sudo -u nix-builder ssh-keygen -t ed25519 -f /var/lib/nix-builder/.ssh/id_ed25519
   

2. Copy the public key to client machines:

   # Add to /var/lib/nix-builder/.ssh/authorized_keys on zix790prors
   

3. On client machines, ensure you can connect:

   ssh nix-builder@zix790prors
   

Configuration Files

Key Files Created/Modified

• flake.nix - Added Jovian input and nix-deck configuration
• roles/jovian-compat.nix - Compatibility shim (remove in 25.11+)
• roles/desktop/steamos.nix - SteamOS/Jovian role abstraction
• roles/remote-build/default.nix - Remote builder role
• machines/nix-deck/configuration.nix - Steam Deck system config
• machines/nix-deck/hardware-configuration.nix - Hardware config (placeholder)

Example Configuration

# machines/nix-deck/configuration.nix
{
  roles = {
    desktop = {
      enable = true;
      wayland = true;
      gaming.enable = true;
      kde = true;
      sddm = true;
      steamos = {
        enable = true;
        autoStart = false;  # or true to boot to Steam UI
        desktopSession = "plasmawayland";
      };
    };
    remote-build.builders = [{
      hostName = "zix790prors";
      maxJobs = 16;
      speedFactor = 4;
    }];
  };
}

Jovian Features

Enabled by Default

• Steam Deck hardware support (jovian.devices.steamdeck.enable)
• Steam UI (jovian.steam.enable)
• Decky Loader plugin system (jovian.decky-loader.enable)

Optional Features

Set in the hardware-configuration.nix:

jovian.devices.steamdeck = {
  enable = true;
  autoUpdate = false;  # Auto-update BIOS/controller firmware
};

Manual Firmware Updates

# BIOS update
sudo jupiter-biosupdate

# Controller update
sudo jupiter-controller-update

# Docking station (connect via USB-C first)
jupiter-dock-updater

Troubleshooting

Remote Builds Not Working

1. Check SSH connectivity:

   ssh nix-builder@zix790prors
   

2. Verify builder is trusted:

   # On zix790prors
   nix show-config | grep trusted-users
   

3. Check build logs:

   journalctl -u nix-daemon -f
   

Jovian Not Working

1. Ensure you're on NixOS 25.05 or the compatibility layer is removed for 25.11+
2. Check Jovian is imported in flake.nix
3. Verify hardware config has jovian.devices.steamdeck.enable = true

Compatibility Layer Issues

If you see an error about jovian-compat.nix being incompatible:

1. You're running NixOS 25.11 or later
2. Remove ./roles/jovian-compat.nix from flake.nix
3. Jovian should work natively on 25.11+

Future Upgrades

Upgrading to NixOS 25.11

1. Update nixpkgs input in flake.nix to 25.11
2. Remove ./roles/jovian-compat.nix from flake.nix imports
3. The assertion in jovian-compat.nix will prevent accidental use
4. Test the build
5. Deploy

Switching to Unstable

If you need Jovian to follow unstable nixpkgs:

1. Edit flake.nix:

   jovian = {
     url = "github:Jovian-Experiments/Jovian-NixOS";
     inputs.nixpkgs.follows = "nixpkgs-unstable";
   };
   

2. This only affects Jovian packages, not your base system

Additional Resources

• Jovian-NixOS Documentation
• Jovian Steam Deck Guide
• NixOS Remote Builds