Install

Install

You need a USB stick, a keyboard, and preferably a wired network connection. The boot menu and the installer ignore controllers; once CouchLiteOS is running, a controller is enough.

Already have CouchLiteOS 0.2.0 or MoonlightOS installed? Do not reinstall: boot the new stick and update the installed system instead, which keeps your pairings and settings (Updating).

1. Download the right ISO

Get the files from the latest release:

File	For
couchliteos-<version>-amd64.iso	General: Intel and AMD graphics, older NVIDIA (Kepler and before), Intel Macs, virtual machines
couchliteos-<version>-nvidia-amd64.iso	NVIDIA Maxwell or newer: GTX 745/750/750 Ti, GTX 800M/900M, GTX 900, GTX 10, GTX 16, RTX 20/30/40
SHA256SUMS	Checksums for the ISOs

Not sure about your NVIDIA card? Use the NVIDIA ISO: it uses NVIDIA's driver only on GPUs that driver supports and the open driver on anything else. See Hardware Compatibility.

The NVIDIA ISO is added to a release a little after the general one. If it is not on the release page yet, check back later, or use the general ISO for now: it runs NVIDIA cards with the open driver, and Moonlight decodes the video in software.

The ISOs are about 1 GB. They have no web browser inside: you pick Firefox or Google Chrome in the Setup Wizard and it installs from the internet (Web Apps and Browsers).

2. Check the download

Compare the ISO's hash with its line in SHA256SUMS:

System	Command
Linux (in the download folder)	sha256sum -c --ignore-missing SHA256SUMS
Windows PowerShell	Get-FileHash .\couchliteos-<version>-amd64.iso -Algorithm SHA256
Windows Command Prompt	certutil -hashfile couchliteos-<version>-amd64.iso SHA256
macOS	shasum -a 256 couchliteos-<version>-amd64.iso

On Windows and macOS, compare the printed hash yourself (case does not matter).

3. Write the USB stick

Write the ISO to the whole stick as a raw image. Everything on the stick is erased. Copying the ISO onto the stick as a file does not work.

• Windows: Rufus (choose DD Image mode when asked) or balenaEtcher.

• Linux: find the stick with lsblk, then

  sudo dd if=couchliteos-<version>-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

• macOS:

  diskutil list                      # find the stick, e.g. /dev/disk4
  diskutil unmountDisk /dev/disk4
  sudo dd if=couchliteos-<version>-amd64.iso of=/dev/rdisk4 bs=4m
  diskutil eject /dev/disk4

  dd prints no progress on macOS; press Ctrl+T to see it.

4. Boot it

1. Connect the display, Ethernet, and a keyboard, and plug in the stick.
2. Open the firmware boot menu while the PC starts: often F12 (Dell), F10, F11, F9 or Esc. Choose the USB entry that starts with UEFI if there is one. On an Intel Mac, hold Option (⌥) and choose EFI Boot.
3. The CouchLiteOS menu starts Start CouchLiteOS after three seconds. Press an arrow key to stop the countdown and pick another entry.

Boot menu entry	Use it when
Start CouchLiteOS	Normal start. Uses a persistence stick if one is plugged in.
Start CouchLiteOS (No Persistence)	A saved setting (for example a display mode the screen cannot show) keeps the screen black. Ignores the persistence stick.
Start CouchLiteOS (Basic Graphics)	NVIDIA ISO only. The screen stays black or misdraws with NVIDIA's driver; uses the open nouveau driver instead.
Install CouchLiteOS	Install to the internal disk (below).

An installed box has one more entry after its first update: CouchLiteOS: restore previous version puts the version from before the update back (Updating).

Secure Boot

CouchLiteOS boots with Secure Boot on, but two drivers do not load with it: NVIDIA's driver (NVIDIA ISO) and Broadcom's wl Wi-Fi driver (both ISOs).

• With Secure Boot on, an NVIDIA box falls back to the open driver (slower). Turn Secure Boot off in the firmware setup to use NVIDIA's driver.
• A Broadcom Wi-Fi chip that needs wl has no Wi-Fi with Secure Boot on. Use Ethernet, a supported adapter, or turn Secure Boot off.

Live USB or installed?

A live USB that keeps nothing starts fresh every boot: it forgets Moonlight pairing, Wi-Fi, Bluetooth pairings and the Setup Wizard at power-off. To keep them, install to a disk (recommended), or keep them on the USB stick (below).

Disk space

A disk of 32 GB or more is recommended. With SAVE BEFORE UPDATE on (the default), every update keeps the system it replaces (about 2 GB), so that you can go back to it, and needs about 7 GB free while it saves it. On a smaller disk, turn SAVE BEFORE UPDATE off in Settings > SOFTWARE UPDATE.

Install to a disk

Installing erases the target disk. Back it up and unplug other drives you care about.

1. Boot the stick, stop the countdown, choose Install CouchLiteOS.
2. Language, location, keyboard: your choice. The layout applies to the installer and text console; the launcher itself uses a US key mapping.
3. Network: wired DHCP is automatic. With no network, choose Do not configure the network at this time; you can set up Wi-Fi later in the launcher. If asked for missing firmware, continue without it.
4. Hostname: couchliteos (any name works); leave the domain empty. The installer does not ask for a user name or passwords: the box needs no account to log in with, and CouchLiteOS starts by itself.
5. Clock: your time zone.
6. Partition disks: Guided - use entire disk (not LVM, not encrypted), pick the target disk and check its size and model, then All files in one partition and Finish partitioning and write changes to disk. Answer Yes to Write the changes to disks? only when the disk is right.
7. Network mirror: No. Everything is copied from the ISO.
8. Software selection / popularity contest: select nothing, answer No.
9. GRUB: UEFI PCs install it automatically. On a legacy BIOS PC, install to the disk you just installed to (for example /dev/sda or /dev/nvme0n1), never a partition and never the USB stick.
10. When it says it is finished, remove the stick and continue.

CouchLiteOS starts and the Setup Wizard opens. An installed box hides the boot menu while boots succeed (it waits 1 second); hold Shift (BIOS) or press Esc (UEFI) while it starts to see it. After a failed boot it shows the menu for 5 seconds by itself.

Keep your settings on the USB stick

For trying CouchLiteOS without installing. Two ways:

SET UP STORAGE ON THIS STICK (easiest)

Boot the stick, then open Settings > SOFTWARE UPDATE > SET UP STORAGE ON THIS STICK and confirm. The free space on the stick (or, on a Ventoy stick, a file next to the ISO) becomes a data area for settings, pairings and apps. The ISO on the stick stays as it is. Restart when it says STORAGE IS READY.

Writing a new ISO to the stick later erases this storage too.

A second persistence stick

A second USB stick can keep your settings, and survives writing a new ISO to the first one. It needs Linux to prepare (Windows and macOS cannot create ext4). You can use CouchLiteOS itself: boot it, plug in the second stick, open TERMINAL (no password needed for sudo in the live session). Never format the ISO stick (it is mounted at /run/live/medium).

lsblk -o NAME,SIZE,MODEL,FSTYPE,LABEL,MOUNTPOINT   # find the SECOND stick
sudo mkfs.ext4 -L persistence /dev/sdX              # ERASES that stick
sudo mkdir -p /mnt/persistence
sudo mount /dev/sdX /mnt/persistence
sudo tee /mnt/persistence/persistence.conf <<'EOF'
/var/lib/couchliteos source=couchliteos-state
/var/log/couchliteos source=couchliteos-logs
/var/lib/tailscale source=tailscale-state
/var/lib/bluetooth source=bluetooth-state
/etc/NetworkManager/system-connections source=nm-connections
EOF
sudo umount /mnt/persistence

Then boot the ISO stick with the persistence stick plugged in and choose Start CouchLiteOS. Do not create the source folders yourself; the first boot fills them.

• Sticks made for MoonlightOS keep working: their old folders are used automatically.
• A persistence stick made without the NetworkManager line forgets Wi-Fi at every reboot; add the line to its persistence.conf.
• A persistence stick is not encrypted. Keep it somewhere you trust.

Next: First Setup. To update later: Updating.