ROG Ally PowerShell Modules¶

Bootible uses a modular PowerShell architecture to configure your ROG Ally. Each module handles a specific aspect of the setup.

Module Overview¶

All modules are idempotent and safe to re-run.

Dependency Graph¶

graph TD
    subgraph Foundation
        H[helpers.ps1<br/>Pure functions]
        R[Run.ps1<br/>Orchestrator]
    end

    subgraph Modules
        V[validate<br/>Dry-run only]
        B[base<br/>Foundation]
        A[apps<br/>Desktop apps]
        G[gaming<br/>Game platforms]
        S[streaming<br/>Game streaming]
        RA[remote_access<br/>VPN & RDP]
        SSH[ssh<br/>SSH server]
        E[emulation<br/>EmuDeck]
        ROG[rog_ally<br/>Device-specific]
        O[optimization<br/>Gaming tweaks]
        P[power<br/>Sleep & power button]
        DISP[display<br/>HDR & refresh rate]
        D[debloat<br/>Privacy tweaks]
        HC[health<br/>Post-install checks]
    end

    R --> H
    R --> V
    R --> B
    B --> A
    B --> G
    B --> S
    B --> RA
    B --> SSH
    B --> E
    B --> ROG
    A --> O
    G --> O
    O --> P
    P --> DISP
    A --> D
    O --> D
    D --> HC

    style H fill:#e1f5fe
    style B fill:#fff3e0
    style D fill:#fce4ec

Load Order¶

Modules execute in this fixed order:

1. helpers.ps1    # Library - always loaded first
2. validate       # Dry-run only - package validation
3. base           # Foundation - hostname, network, winget
4. apps           # Desktop applications
5. gaming         # Game platforms & launchers
6. streaming      # Game streaming clients
7. remote_access  # VPN & remote desktop
8. ssh            # SSH server configuration
9. emulation      # EmuDeck setup
10. rog_ally      # Device-specific tools
11. optimization  # Windows gaming tweaks
12. power         # Sleep-to-hibernate, power button, CPU boost
13. display       # HDR toggle and refresh rate
14. debloat       # Privacy & performance tweaks
15. health        # Post-install health checks

Why this order matters:

• base initializes winget before any package installs
• apps installs PowerShell 7 which ssh and debloat can use
• optimization configures Steam settings (requires Steam from gaming)
• debloat runs after all installs to configure the installed applications
• health runs last - read-only checks that verify what the run claims to have done

validate¶

Purpose: Pre-flight validation of all winget package IDs

Runs: Dry-run mode only

Validates that all package IDs in the configuration exist in winget sources. Reports which packages are available and which are missing.

Example Output:

Validating packages...
  ✓ Discord.Discord
  ✓ Spotify.Spotify
  ✗ Invalid.PackageID - Not found in winget

base¶

Purpose: System foundation and prerequisites

Config Keys:

What It Does:

1. Sets hostname if specified
2. Configures static IP or DHCP
3. Installs optional package managers (Chocolatey, Scoop)
4. Optimizes winget source updates
5. Installs essential utilities (7-Zip, Everything, PowerToys)
6. Creates games_path/roms_path directories if configured (drive-letter paths only; Steam library registration stays manual — Steam > Settings > Storage)

apps¶

Purpose: Desktop application installation

Master Key: install_apps (default: true)

Application Categories:

Example:

install_apps: true
install_discord: true
install_spotify: true
password_managers:
  - "1password"
install_powershell7: true  # PowerShell 7

gaming¶

Purpose: Gaming platforms and utilities

Master Key: install_gaming (default: true)

Platforms:

Battle.net Note:

Battle.net uses a non-standard installer. Bootible downloads and launches it; you complete installation manually. battle_net_location (default %ProgramFiles(x86)%\Battle.net, not in config.yml) overrides where Bootible looks for an existing install.

streaming¶

Purpose: Game streaming clients

Master Key: install_streaming (default: true)

remote_access¶

Purpose: VPN and remote desktop tools

Master Key: install_remote_access (default: false)

RDP Configuration:

When enable_rdp: true, Bootible:

1. Enables Remote Desktop in the registry (fDenyTSConnections = 0)
2. Enables the built-in "Remote Desktop" firewall rule group

ssh¶

Purpose: Windows OpenSSH server configuration

Master Key: install_ssh (default: false)

What It Does:

1. Installs OpenSSH Client/Server Windows capability
2. Sets sshd and ssh-agent services to automatic start
3. Imports the listed authorized keys from the private repo
4. Configures PSRemoting over SSH (if PowerShell 7 installed)
5. Creates firewall rules for SSH and ICMPv4 (ping)

Key Import:

ssh_authorized_keys:
  - "desktop.pub"
  - "laptop.pub"

Keys are read from private/ssh-keys/ (or private/files/ssh-keys/) and written to C:\ProgramData\ssh\administrators_authorized_keys with locked-down ACLs.

emulation¶

Purpose: EmuDeck installation

Master Key: install_emulation (default: false)

What It Does:

1. Checks for existing EmuDeck installation (skips if found)
2. Pre-installs EmuDeck's prerequisites (Git, Python 3.12) via winget
3. Uses the EA (Patreon) installer from private/scripts/ if available
4. Falls back to the public EmuDeck installer

EmuDeck itself configures emulators interactively — finish setup in the EmuDeck app. The roms_path/games_path keys only scaffold directories (see base); they don't configure EmuDeck.

Patreon Version:

private/scripts/EmuDeck EA Windows.bat

rog_ally¶

Purpose: ASUS ROG Ally-specific tools

Master Key: install_rog_ally (default: true)

Armoury Crate:

Bootible verifies Armoury Crate is present (usually pre-installed) but doesn't modify it.

optimization¶

Purpose: Windows gaming optimizations

Master Key: install_optimization (default: true)

Security Trade-offs:

power¶

Purpose: Sleep-to-hibernate conversion and power-button behavior via powercfg

All keys default to off - the module changes nothing unless you opt in.

display¶

Purpose: HDR toggle and refresh rate for the internal panel

Both keys default to "leave alone" — the module changes nothing unless you opt in.

HDR: uses HDRCmd from the HDRTray project, downloaded automatically on first use and cached locally. It handles the Windows 11 24H2 Auto Color Management edge case where the built-in toggle may not fully activate HDR.

Refresh rate: only panel-supported modes are applied. An unsupported rate is skipped with a warning listing the available rates.

debloat¶

Purpose: Privacy and performance tweaks

Master Key: install_debloat (default: true)

Privacy Settings¶

UI Settings¶

Edge Debloating¶

Network & Performance¶

PowerShell¶

Personalization¶

Image Paths:

Reference images from your private repo:

wallpaper_path: "Images/wallpaper.jpg"
lockscreen_path: "Images/lockscreen.jpg"

Images are copied from private/device/rog-ally/<device>/Images/.

health¶

Purpose: Post-install health checks

Master Key: post_install_health_checks (default: true)

Read-only checks that verify what the run claims to have done — e.g. Game Mode and HAGS registry state, SSH server state (ssh_server_enable), RDP (enable_rdp), time sync (force_time_sync), and presence of key installs (Steam, Git, PowerShell 7). Runs last and changes nothing.

Selective Module Execution¶

Run Specific Modules¶

cd $env:USERPROFILE\bootible\config\rog-ally

# Only base and apps
.\Run.ps1 -Tags base,apps

# Only gaming-related
.\Run.ps1 -Tags gaming,streaming,emulation

# Dry run specific modules
.\Run.ps1 -Tags optimization,debloat -DryRun

Skipping Modules¶

There is no skip flag. To skip a module, either pass -Tags listing every module you do want, or disable the module in config (see below).

Dependencies Not Auto-Included¶

Running -Tags apps without base may fail if winget sources aren't initialized. Include dependencies manually.

Disabling Modules¶

Disable modules via configuration:

install_apps: false
install_gaming: false
install_streaming: false
install_remote_access: false
install_ssh: false
install_emulation: false
install_rog_ally: false
install_optimization: false
install_debloat: false

Re-run Behavior¶

Always Safe¶

• Package installs (winget skips installed)
• Registry settings (same value = no change)
• Service configuration (checks state first)
• Firewall rules (checks existing rules)

Minor Effects on Re-run¶

• Wallpaper/lock screen: Re-copies images
• Desktop shortcuts: Re-cleans desktop
• UCPD scheduled task: Re-creates task

Checks Before Acting¶

• Hostname: Only changes if different
• Static IP: Only if not configured
• EmuDeck: Only if not detected
• OpenSSH: Only if capability not present

Troubleshooting¶

Module Didn't Run¶

1. Check if enabled: install_<module>: true
2. Check -Tags includes module
3. Review transcript log for skip messages

Package Install Failed¶

1. Run dry-run to validate: .\Run.ps1 -DryRun
2. Check winget: winget source list
3. Reset: winget source reset --force

Registry Changes Not Applied¶

1. Some HKCU keys need non-elevated context
2. debloat creates scheduled task for UCPD keys
3. Log out/in to apply scheduled changes

SSH Not Working¶

1. Check service: Get-Service sshd
2. Check firewall: Get-NetFirewallRule -DisplayName "*SSH*"
3. Check keys: C:\ProgramData\ssh\administrators_authorized_keys