Install Rare OS

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

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

1. Turn on remote access

   On the SuiPlay, open Settings, then Advanced, and turn on Remote Access. Then open Settings, Internet, your Wi-Fi network, and note the IP address.

2. Sign in from a computer

   On a computer on the same Wi-Fi, open a terminal (on Windows, PowerShell) and sign in to the SuiPlay:

   Terminal

   ssh playtron@<the IP address>

   The password is playtron.

3. Run the install command

   Terminal

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

   Answer y when it asks. It downloads about 8 GB, which takes 10 to 30 minutes on good Wi-Fi.

4. Restart

   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.

No computer? 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 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:

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

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 devices that do not boot from an image (SteamOS, Windows, most Linux installs), or for a clean start. Games and files on the internal drive are gone. Games on an SD card stay, and Rare Launcher picks them up.

Make the stick

1. Download the installer

   Download rare-os-installer.iso from rare.market/os once it is published.

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.

   • 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 in the stick.

2. Start from the stick

   Open the firmware boot menu and pick the USB stick.

3. Confirm or cancel

   The installer shows one screen. It names the internal drive it will erase and counts down from 20 seconds. Hold the power button to cancel. Otherwise it installs and restarts into Rare OS by itself, in about 10 minutes.

Open the firmware boot menu

On AYANEO-made handhelds (the SuiPlay0X1 is one) this is usually done by holding a volume key while pressing power. Check your device's manual: this has not been confirmed on a SuiPlay yet. On other PCs it 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.

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:

sudo bootc upgrade