Skip to content
⌘K

For players

Install Rare OS

Switch a SuiPlay0X1 to Rare OS in place, try it from a USB-C drive, use the USB-C installer, go back to your old system, and how updates work.

There are three ways to install Rare OS. Every one of them can be undone. If you are not sure, start with the first.

Switch in placeTry it from a USB-C driveUSB-C installer
ForSuiPlay0X1, and other image-based Linux handhelds and PCsTesting without changing the SuiPlayAny x86_64 handheld or PC, or a clean start
NeedsWi-Fi, about 20 GB free, and a computer or phone on the same Wi-Fi, or a USB-C keyboardA USB-C SSD and a Linux computer with podmanA USB-C stick of 16 GB or more
Your files and gamesKeptUntouched (Rare OS lives on the SSD)Internal drive erased. Games on the SD card stay
UndoOne command, or pick the old system in the boot menuUnplug the driveReinstall the old system from its own installer

If your SuiPlay has a Playtron wallet with anything in it, move those assets first. That wallet can only sign through the original system's sign-in. See Move from a Playtron wallet.

Before you start

  • Charge the SuiPlay. The install command needs 30% battery or more, or the charger connected. Keeping it on the charger is best.
  • Free about 20 GB on the system drive.
  • Back up anything you cannot lose. Switching in place keeps your files, but a backup costs nothing.
  • A USB-C keyboard or hub helps with the boot menu and a terminal.

Switch in place

Rare OS downloads over Wi-Fi and installs next to your current system. Your home folder, Steam library, installed games, Flatpak apps, Wi-Fi networks and Bluetooth pairings stay. The old system stays installed as the fallback.

On a SuiPlay0X1, from a computer

  1. Turn on remote access

    On the SuiPlay, open Settings, then Advanced, and turn on Remote Access. Then open Settings, Internet, Registered Wi-Fi networks, pick your network, and note its IP address (like 192.168.0.42).

  2. Sign in from a computer

    On a computer on the same Wi-Fi, open a terminal:

    • Windows: PowerShell. Search for it in the Start menu.
    • Mac: Terminal. Search for it with Spotlight.
    • Linux: any terminal.

    Sign in to the SuiPlay, with your IP address in place of the example:

    Terminal
    ssh [email protected]

    Type yes if it asks whether to continue connecting. The password is playtron. Nothing shows as you type.

  3. Run the install command

    Terminal
    curl -fsSL https://rare.market/os/get | sudo bash

    Enter playtron again, and answer y when it asks. It downloads about 8 GB, which takes 10 to 30 minutes on good Wi-Fi. Keep the computer awake until it finishes, and don't install a GameOS update while it runs.

  4. Restart

    When it asks "Restart now?", type y, or run:

    Terminal
    sudo reboot

    The SuiPlay starts in Rare OS, on Rare Launcher.

  5. Change the default password

    In Rare OS, switch to desktop mode (Quick settings, Desktop mode), open a terminal and run passwd. The old default password is publicly known.

If the connection drops while it downloads (the computer sleeps, or the Wi-Fi blips), the download stops and nothing is changed. Sign in again and run the same command: it keeps what it already downloaded.

No computer or phone? Plug a USB-C keyboard into the SuiPlay, press Ctrl + Alt + F3, sign in with the same user and password, and run the command there.

On a SuiPlay0X1, from a phone

The same switch works from a phone with a free SSH app. The phone must be on the same Wi-Fi as the SuiPlay, not on mobile data.

A phone drops the connection when the screen locks or the app goes to the background, and the usual command stops when that happens. Nothing breaks, but you would have to keep the app open and the screen on for the whole download. The command below runs the install on the SuiPlay itself instead, so the phone can sleep.

  1. Turn on remote access

    On the SuiPlay, open Settings, then Advanced, and turn on Remote Access. Then open Settings, Internet, Registered Wi-Fi networks, pick your network, and note its IP address. Keep the SuiPlay plugged in.

  2. Install an SSH app

    • iPhone: Termius, from the App Store.
    • Android: Termius from Google Play, or Termux.

    Termius may offer an account or a paid plan. Skip it: the free app is enough.

  3. Sign in to the SuiPlay

    In Termius, tap +, then New Host. Enter the SuiPlay's IP address, the username playtron and the password playtron, tap Save, then tap the new host to connect. If it asks whether to trust the SuiPlay, accept.

    In Termux, run these two commands instead. Type y if asked, then yes, then the password playtron:

    Termux
    pkg install openssh
    ssh [email protected]
  4. Start the install

    Copy this command, long-press in the app and tap Paste, then enter playtron when asked:

    Terminal
    sudo systemd-run --collect --unit=rare-os-get -E RARE_YES=1 -E RARE_REBOOT=1 bash -c 'curl -fsSL https://rare.market/os/get | bash'

    It runs the same install as a background job on the SuiPlay, answers yes for you, and restarts the SuiPlay into Rare OS when it is done. You can now lock the phone or close the app. Don't install a GameOS update while it runs.

  5. Watch it (optional)

    Terminal
    tail -F /var/log/rare-os-get.log

    It runs the same five checks as on a computer, then downloads about 8 GB, which takes 10 to 30 minutes on good Wi-Fi. If a line starts with ✗, do what it says, then run the command from the previous step again. Close the app at any time: the install keeps going.

  6. Change the default password

    In Rare OS, switch to desktop mode (Quick settings, Desktop mode), open a terminal and run passwd. The old default password is publicly known.

On other image-based Linux handhelds and PCs

Systems that boot from a container image (bootc or rpm-ostree, such as Fedora Atomic) can switch the same way. Open a terminal (desktop mode, or Ctrl + Alt + F3) and run:

Terminal
curl -fsSL https://rare.market/os/get | sudo bash
sudo reboot

What the command checks

The command shows a QR code that opens these instructions on a phone, then runs five numbered steps. If one fails, it stops with a plain explanation and nothing is changed.

  1. Device: an x86_64 machine that boots from an image. If it already runs Rare OS, it says so and stops.
  2. Power: battery at 30% or more, or the charger connected.
  3. Space: about 20 GB free on the system drive.
  4. Network: the download server answers, and the Rare OS image is published.
  5. Switch: it lists what stays, what changes and how to undo, asks once, then switches.

Every run is logged to /var/log/rare-os-get.log on the device, in case you need help.

The first download is checked over HTTPS, because your old system does not have Rare's signing key. Rare OS carries the key, and from its first start every update must carry a valid Rare signature.

What is kept

KeptYour home folder, Steam and other game libraries, downloaded games, Flatpak apps, Wi-Fi networks and Bluetooth pairings
MergedSystem settings are carried over and merged with Rare OS's defaults
ReplacedThe operating system itself. The original system's own apps are not part of Rare OS

Rare Launcher scans Steam libraries, Games folders, other users' home folders and SD cards, so games already on the device show up in its library. On the SuiPlay, your existing user and home folder are used as they are.

Try it from a USB-C drive

Rare OS lives on an external USB-C SSD and the SuiPlay's internal drive is never touched. This is the safest way to try it.

  1. Write Rare OS to the SSD

    On a Linux computer with podman, plug in the SSD and install the Rare OS image to it with bootc install to-disk. Use lsblk to find the SSD. This erases the SSD.

  2. Boot the SuiPlay from the SSD

    Plug the SSD into the SuiPlay. Power on into the firmware boot menu (see Open the firmware boot menu) and pick the USB drive.

  3. Go back

    Power off and unplug the SSD. The SuiPlay starts your old system exactly as it was.

USB-C installer

The installer erases the internal drive and installs a clean Rare OS. It is for a SuiPlay running Windows or SteamOS, other devices that do not boot from an image, or a clean start. Games and files on the internal drive are gone, and so is the old system. Games on an SD card stay, and Rare Launcher picks them up.

Make the stick

  1. Download the installer

    Download rare-os-installer.iso (about 8 GB) from rare.market/os. The page shows its SHA-256, which is also at rare.market/os/rare-os-installer.iso.sha256. To check the download: certutil -hashfile rare-os-installer.iso SHA256 on Windows, shasum -a 256 rare-os-installer.iso on macOS, sha256sum rare-os-installer.iso on Linux.

    The same file is on the GitHub release in parts, because GitHub takes files up to 2 GB. Joined in order they are the ISO: cat rare-os-installer.iso.part* > rare-os-installer.iso on macOS and Linux, or copy /b rare-os-installer.iso.part0 + rare-os-installer.iso.part1 + rare-os-installer.iso.part2 + rare-os-installer.iso.part3 rare-os-installer.iso in a Windows command prompt.

  2. Write it to a USB-C stick

    Use a stick of 16 GB or more and one of these apps. A browser can't write a USB stick, so one of them is needed. Everything on the stick is replaced.

    • Fedora Media Writer (Windows, macOS, Linux): "Select .iso file", pick the stick, "Write".
    • balenaEtcher (Windows, macOS, Linux): "Flash from file", "Select target", "Flash".
    • Rufus (Windows): pick the ISO, keep "GPT" and "UEFI", and choose DD image mode when asked.

Install

  1. Plug in the stick

    Power off the handheld and plug the stick into a USB-C port.

  2. Start from the stick

    Open the firmware boot menu and pick the USB stick. See Open the firmware boot menu.

  3. Confirm or cancel

    The installer shows one screen. It names the internal drive it will erase and counts down from 20 seconds. To cancel, hold the power button until the screen goes off: nothing has been written yet. Otherwise it installs and restarts into Rare OS by itself, in about 10 minutes.

    It only ever picks the internal drive (an NVMe drive first). The USB stick, other USB drives and the SD card are never touched.

  4. Unplug the stick

    When Rare OS has started, unplug the stick. The installer puts Rare OS first in the firmware's boot order, so the restart goes to Rare OS even with the stick still in. If the installer screen comes back instead, hold the power button to turn off, unplug the stick and power on.

With Secure Boot on, the installer says so on its screen before it starts. Rare OS's kernel is signed with Universal Blue's key, so the first start shows a blue screen once: plug in a USB-C keyboard, press Down to Enroll MOK, then Continue, Yes, type the password rare, then Reboot. No keyboard? Cancel the installer, turn Secure Boot off in the firmware settings, and start again.

Open the firmware boot menu

On a SuiPlay0X1: power off, then hold Volume Up and LC and press Power. The boot menu lists the USB stick; it also has Enter Setup for the firmware settings.

This is the combination AYANEO documents for the AYANEO 2S, which the SuiPlay0X1 is built on, and the one Playtron gives for AYANEO handhelds. It has not been tried on a SuiPlay yet, and the SuiPlay has its own firmware, so it may differ. With a USB-C keyboard in the other port, pressing F7 while it starts opens the same menu on the AYANEO 2S. A keyboard's arrow keys and Enter always work in the menu; without one, AYANEO handhelds are reported to move with the AYANEO button and pick with Volume Up, which is not confirmed on a SuiPlay either.

Whether a SuiPlay starts from the stick by itself when its internal drive has no system is not known yet. Use the boot menu.

On other PCs the boot menu key is usually F12, F7 or Esc with a keyboard attached.

Go back to your old system

After a switch in place

Your previous system stays installed next to Rare OS. Any of these brings it back:

  • From Rare OS: open a terminal in desktop mode and run the command below, then restart.

    Terminal
    sudo bootc rollback && sudo reboot

    On older rpm-ostree systems, use sudo rpm-ostree rollback instead.

  • From the boot menu: with a USB-C keyboard plugged in, hold Shift (or tap Esc) while powering on, and pick the older entry.

  • After a failed start: the boot menu appears by itself after a start that did not finish.

Rollback swaps which of the two installed systems starts. Your files are the same in both. Run the same command again to go forward to Rare OS.

The system you switched from is pinned when Rare OS first starts, so updates never remove it. It stays in the boot menu, which matters while a Playtron wallet still needs the original system to sign its moves. Once you no longer need it, find its index and unpin it. The next update then removes it.

Terminal
rpm-ostree status
sudo ostree admin pin --unpin <index>

After a USB-C drive

Unplug the drive.

After the USB-C installer

Reinstall the previous system from its own installer. A USB-C install cannot be rolled back in place.

Updates

Rare OS updates itself in the background. Each update is a complete, signed system image, and it is applied on the next restart. The previous version stays installed as the fallback, so updates work exactly like the switch: if one misbehaves, pick the previous version in the boot menu or run sudo bootc rollback.

Settings, System, Updates shows that updates are automatic. To check for an update by hand, open a terminal in desktop mode and run:

Terminal
sudo bootc upgrade
--
TPS:--