Skip to content

Getting Started

Welcome to Bootible! This guide will walk you through setting up your gaming handheld from scratch.

Choose Your Path

  • Quick Start

    Jump straight in with the one-liner command. Perfect if you just want to see what Bootible does.

    Quick Start

  • First Run Walkthrough

    Step-by-step guide through your first Bootible run with explanations of each stage.

    First Run

  • Private Configuration

    Set up your own private GitHub repo to store and sync your personal configuration.

    Private Config

  • Multi-Device Setup

    Configure multiple devices (handhelds, PCs) from a single config repository.

    Multi-Device

Prerequisites

Before running Bootible, make sure you have:

  • Steam Deck with internet connection
  • Desktop Mode access (hold power button → Switch to Desktop, or press Steam button → Power → Switch to Desktop)

  • Sudo password set — from Desktop Mode, open Konsole and run passwd to set your password

    Save your password

    Store this password in your password manager of choice. You'll need it when running Bootible.

  • Optional: GitHub account for private config

  • ROG Ally with Windows 11 and internet
  • PowerShell running as Administrator
  • Windows Terminal installed (comes with Windows 11)
  • Optional: GitHub account for private config

What Happens When You Run Bootible

sequenceDiagram
    participant User
    participant Bootstrap
    participant Config
    participant Installer

    User->>Bootstrap: Run one-liner command
    Bootstrap->>Bootstrap: Detect device type
    Bootstrap->>User: Prompt for private repo (optional)
    Bootstrap->>Config: Load defaults + private config
    Bootstrap->>User: Show dry-run preview
    User->>Bootstrap: Run 'bootible' to apply
    Bootstrap->>Installer: Install packages & configure
    Installer->>Bootstrap: Push logs to private repo
    Bootstrap->>User: Show summary
  1. Detection — Bootible identifies your device type
  2. Configuration — Loads defaults and merges your customizations
  3. Preview — Shows exactly what will change (dry-run)
  4. Apply — Installs packages and applies settings
  5. Log — Pushes run logs to your private repo

Frequently Asked Questions

Is it safe to run?

Yes! Bootible runs in dry-run mode by default. The first run shows you exactly what would happen without making any changes. Only when you run bootible afterward are changes applied.

Additionally:

  • Windows: Creates a System Restore Point before making changes
  • Steam Deck: Creates a btrfs snapshot before making changes
Do I need a GitHub account?

No, GitHub is optional. Without it:

  • You can still run Bootible with default settings
  • Logs are saved locally instead of pushed to a repo
  • You miss out on syncing configs across devices

With a GitHub account:

  • Store your personal configuration in a private repo
  • Sync settings across multiple devices
  • Run logs are automatically pushed for debugging
Can I undo changes?

Yes!

  • Windows: Use System Restore to revert to the pre-Bootible state
  • Steam Deck: Restore from the btrfs snapshot created before running
What if I run it multiple times?

Bootible is idempotent — running it multiple times is safe. It will:

  • Skip packages already installed
  • Update configurations if they've changed
  • Not duplicate any settings