Le guide d'ESO OS

# ESO OS 2.3 — the complete tutorial

ESO OS is a Linux operating system built on Debian 13 "trixie" with a newer desktop stack (Linux 7.1, Mesa 26.1,
Hyprland 0.55). On top of that sits **ESO Desktop**, a Windows 11-style desktop where every app is a native
program (GTK / X11 / Wayland). It idles at about 350–420 MB of RAM and near 0 % CPU.

**New in 2.3:** every window is a real Windows-style window. Each app, including This PC, Recycle Bin, Settings,
Store and Task Manager, has a title bar with **— □ ✕** (minimize, maximize/restore, close). Double-click the title bar to
maximize or restore. Resize from any edge or corner, overlap windows freely, drag a window to a screen edge to snap it,
and keep any window **Always on top** (`WIN+CTRL+T`, or right-click the title bar). The taskbar now has a button for every open
window. The ESO Store installs Steam and other Flathub apps again (the *"No remote refs found for 'flathub'"* error is
fixed). See [Windows](#windows-title-bars-resize-snap-always-on-top).

**New in 2.2:** Matrix is now one terminal for every shell: Matrix (zsh), Bash, PowerShell 7, Ubuntu, Arch, Fedora,
Alpine, Command Prompt, Administrator, Python and SSH, in tabs and split panes. It is drawn on the CPU, so it needs no
graphics card. See [Matrix](#matrix-one-terminal-for-every-shell-win-enter-or-cmd-in-run).

This guide covers everything from downloading to troubleshooting. Short on time? Read **[1](#1-download-and-check)**,
**[2](#2-run-it-in-a-virtual-machine)** or **[3](#3-install-it-on-a-pc)**, then the **[shortcuts](#keyboard-shortcuts)**.

**Contents**

1. [Download and check](#1-download-and-check)
2. [Run it in a virtual machine](#2-run-it-in-a-virtual-machine) — VirtualBox, VMware, QEMU/virt-manager, Hyper-V
3. [Install it on a PC](#3-install-it-on-a-pc) — USB stick, live session, installer
4. [First steps](#4-first-steps)
5. [The desktop](#5-the-desktop) — Start, taskbar, **windows (title bars, resize, snap, always on top)**, desktop icons, right-click, notifications
6. [Keyboard shortcuts](#keyboard-shortcuts)
7. [Run (WIN+R)](#7-run-winr)
8. [WIN+X, Quick settings, CTRL+ALT+Del, ALT+Tab](#8-winx-quick-settings-ctrlaltdel-alttab)
9. [The ESO apps](#9-the-eso-apps) — Matrix, Files, Browser, Store, Settings, Task Manager, Defender, Lock
10. [Personalize](#10-personalize) — wallpaper (live 4K video), Start menu shape and position, taskbar, cursor, scale
11. [Gaming](#11-gaming) — Steam, Epic Games, game mode
12. [Speed](#12-speed) — performance profiles, background apps, light session
13. [Troubleshooting](#13-troubleshooting) — screen too big, slow VM, no network, won't boot, forgotten password
14. [Updating](#14-updating)
15. [Settings file reference](#15-settings-file-reference)
16. [FAQ and honest limits](#16-faq-and-honest-limits)

---

## 1. Download and check

From **https://gofile.io/d/EkIhixrY** download what you need:

| File | Use it for |
|---|---|
| `eso-os-2.3.0-amd64.iso` | Live USB stick, or installing on a PC or in any VM (BIOS and UEFI, Secure Boot works) |
| `eso-os-2.3.0-vm.qcow2` | Already-installed disk for QEMU/KVM, virt-manager, Proxmox, GNOME Boxes, UTM, and Hyper-V after conversion |
| `eso-os-2.3.0-vm.vmdk` | Already-installed disk for VirtualBox and VMware |
| `SHA256SUMS-2.3.0.txt` | Checksums |
| `tutorial.md` | This guide |

**Check the download** (a damaged download is the most common reason an ISO "doesn't boot"):

- Windows (PowerShell): `Get-FileHash .\eso-os-2.3.0-amd64.iso -Algorithm SHA256`
- Linux / macOS: `sha256sum eso-os-2.3.0-amd64.iso` (macOS: `shasum -a 256 …`)

The result must match the line in `SHA256SUMS-2.3.0.txt`.

**Logins**

| Where | User | Password |
|---|---|---|
| Live USB session | `eso` | `live` |
| VM images (qcow2 / vmdk) | `eso` | `eso` (change it: Settings → Users, or `passwd` in Matrix) |
| Installed from the ISO | the user you create in the installer | your password |

> Delete any older ESO files (1.0.0 / 2.0.0) you still have. 1.0.0 opened at 200 % scale in some VMs and did not have
> the speed fixes. 2.3.0 starts at 100 % and picks the resolution automatically.

---

## 2. Run it in a virtual machine

### Settings that matter in every VM app

| Setting | Use | Why |
|---|---|---|
| Hardware virtualisation (VT-x / AMD-V / KVM / Hyper-V platform) | **On** | Without it every VM is 10–50× slower, whatever the OS. Turn it on in your PC's BIOS/UEFI (often called *Intel Virtualization Technology* or *SVM Mode*) |
| CPUs | **2 or more** | |
| RAM | **2 GB or more** (1 GB works, 4 GB is comfortable) | |
| Disk | the image grows up to 20 GB | |
| Display scale in the VM app | **100 %** | Otherwise the VM app enlarges the whole screen 2× (see [13.1](#131-everything-is-too-big-200-)) |

ESO starts **ESO Desktop** (X11 + xfwm4 + picom), which needs no GPU and is fast in every VM. The optional
Hyprland session is only for PCs with a real graphics card.

### VirtualBox (7.x)

1. **New** → Name `ESO`, Type **Linux**, Version **Debian (64-bit)**. Do not choose an ISO if you use the `.vmdk`.
2. Memory **2048 MB or more**, Processors **2 or more**, and tick **Enable EFI** (optional; both BIOS and EFI boot).
3. Hard disk: **Use an existing virtual hard disk file** → pick `eso-os-2.3.0-vm.vmdk`.
   (Or create an empty 25 GB disk and attach the ISO to install it yourself.)
4. **Settings → Display → Screen:**
   - Graphics Controller **VMSVGA**, Video Memory **128 MB**
   - **Scale Factor 100 %**
   - **Enable 3D Acceleration: off** (ESO's light session does not need it; VirtualBox's 3D layer makes things slower)
5. **Settings → System → Processor:** tick **Enable PAE/NX**. Under **Acceleration**, Paravirtualization Interface
   **Default** or **KVM**, and nested paging **on**.
6. Start. After the VM window opens: **View → Virtual Screen 1 → Scale to 100 %** (the menu is called
   **Scaled Mode / Scale factor** in some versions). On Windows hosts with a 150–200 % display, also turn **off**
   *View → Use Unscaled HiDPI Output* if you see it, or turn it **on** if everything is still doubled. Try both
   and keep the one that looks sharp and normal-sized.
7. Pick the resolution with **Settings → Display** inside ESO, or maximize the VM window. ESO picks the largest mode up to
   1920×1080 automatically.

If VirtualBox shows "VT-x is not available", Hyper-V/WSL is taking it on Windows. Either keep them and accept the
slower speed, or turn them off: `bcdedit /set hypervisorlaunchtype off` in an admin prompt, then reboot.

### VMware Workstation / Player / Fusion

1. **File → Open** does not accept a bare `.vmdk`. Instead use **Create a New Virtual Machine → Custom → I will install
   the OS later → Linux / Debian 12.x 64-bit** (or newer).
2. 2 CPUs, 2 GB+ RAM. At the disk step: **Use an existing virtual disk** → `eso-os-2.3.0-vm.vmdk`
   (keep the existing format if asked).
3. VM Settings → Display: **Accelerate 3D graphics off**. Clear **Automatically adjust user interface size in the
   virtual machine**, or set **Stretch mode** off so VMware does not scale the guest.
4. ESO includes `open-vm-tools`, so the resolution follows the VM window and copy/paste works.

### QEMU / KVM, virt-manager, GNOME Boxes, Proxmox, UTM

- **virt-manager:** New VM → **Import existing disk image** → `eso-os-2.3.0-vm.qcow2` → OS *Debian 13* (or 12) →
  2 GB, 2 CPUs. Video **Virtio** (or QXL), Display **Spice**. ESO includes `spice-vdagent`, so resolution follows the window.
- **Command line:**
  ```bash
  qemu-system-x86_64 -enable-kvm -cpu host -m 2048 -smp 2 \
    -drive file=eso-os-2.3.0-vm.qcow2,if=virtio -vga virtio -display gtk \
    -device qemu-xhci -device usb-tablet -nic user,model=virtio-net-pci
  ```
  Without `-enable-kvm` (no hardware virtualisation) it will be very slow.
- **Proxmox:** create a VM without a disk, then `qm importdisk <vmid> eso-os-2.3.0-vm.qcow2 local-lvm`, attach it as
  VirtIO SCSI and make it the boot disk.
- **UTM (Intel Macs):** Virtualize → Linux → import the qcow2. (Apple-silicon Macs need an arm64 build; ESO is amd64 only today.)

### Hyper-V (Windows 10/11 Pro)

1. Convert the disk (with `qemu-img` for Windows, or from any Linux):
   `qemu-img convert -p -O vhdx eso-os-2.3.0-vm.qcow2 eso-os-2.3.0.vhdx`
2. Hyper-V Manager → New VM → **Generation 2** → 2048 MB or more (turn **Dynamic Memory off**) → attach the `.vhdx`.
3. VM Settings → **Security → Secure Boot template: Microsoft UEFI Certificate Authority** (or turn Secure Boot off).
4. Processors: 2. Then start the VM.
5. Hyper-V does not resize Linux screens by itself. Set a resolution once, in PowerShell as admin, with the VM switched off:
   `Set-VMVideo -VMName ESO -HorizontalResolution 1920 -VerticalResolution 1080 -ResolutionType Single`
6. In the connection window, **View → Zoom level → 100 %**.

---

## 3. Install it on a PC

### 3.1 Make a USB stick (8 GB or larger; it will be erased)

- **Windows:** [Rufus](https://rufus.ie) → select the ISO → when asked, choose **DD Image mode** → Start.
  Or [balenaEtcher](https://etcher.balena.io), or copy the ISO onto a [Ventoy](https://www.ventoy.net) stick.
- **Linux:** `sudo dd if=eso-os-2.3.0-amd64.iso of=/dev/sdX bs=4M status=progress oflag=sync`
  (`lsblk` shows which `/dev/sdX` is the stick. Choosing the wrong one erases that disk.)
- **macOS:** balenaEtcher.

### 3.2 Boot from it

1. Plug in the stick and restart. Press the boot-menu key while the logo shows: usually **F12**, **F11**, **F8**, **Esc**
   or **F9** (Lenovo: F12 or the Novo button; HP: F9; ASUS: F8/Esc; Dell: F12; MSI: F11; Acer: F12).
2. Pick the USB stick (on UEFI PCs choose the entry starting with **UEFI:**).
3. Secure Boot can stay **on**: ESO uses Debian's Microsoft-signed boot loader.
4. The ESO boot menu appears: press **Enter** on the first entry to start the live session. If the screen stays black,
   restart and choose the **fail-safe mode** entry (under *Advanced options* on UEFI PCs).
   The installed system's own boot menu waits only 1 second.

The **live session** runs from the stick without touching your disk. Try everything first; settings are lost at shutdown.

### 3.3 Install

1. Double-click **Install ESO OS** on the desktop.
2. Choose language, region/time zone and keyboard.
3. **Partitions:**
   - **Erase disk**: ESO takes the whole disk (everything on it is deleted).
   - **Install alongside**: keeps Windows. Drag the divider to pick how much space ESO gets (at least 20 GB, 50 GB+ is
     better). Back up first and turn off Windows *Fast Startup* (Control Panel → Power Options) and BitLocker, if used.
   - **Manual**: for experts.
4. Create your user and password. Tick **Log in automatically** if you want to skip the login screen.
5. Install (about 5–15 minutes) → **Restart now** → remove the stick when told.

The first start of the installed system prepares the Defender's file bank in the background. The login screen does
not wait for it; it finishes about a minute later at idle priority, so you won't notice it.

### 3.4 Dual-boot with Windows

After installing alongside Windows, the ESO boot menu lists **Windows Boot Manager**. If the PC always starts
Windows instead, open the UEFI setup (F2/Del at power-on) and put **ESO** (or *debian*) first in the boot order.

### 3.5 One boot mode

The ESO USB stick has **one** boot entry, "ESO OS", and starts it immediately: no menu, no choices. The installed
system does the same: the boot menu is hidden and ESO starts after 1 second. Hold **Esc** while the PC starts to see the
menu (advanced options and **Defender recovery**). On PCs that also have Windows, the menu shows for 5 seconds so you
can pick Windows.

---

## 4. First steps

### 4.1 ESO Setup (the first-start configuration)

The first time you sign in (live session, VM image or a fresh install), **ESO Setup** opens, like the Windows 11
first-start screens. It takes about a minute:

| Step | What you choose |
|---|---|
| Language | 22 languages including Arabic, French, English, Spanish, German, Turkish, Russian, Chinese |
| Region & time | Time zone (search a city, or **Detect from the internet**), automatic time |
| Keyboard | Layout (changes as you click, with a box to try it) and an optional second layout (**WIN+Space** switches) |
| Display | **Scale 80 / 100 / 125 / 150 %** (applies instantly), automatic resolution on/off |
| Personalize | Taskbar auto-hide, Start menu position and shape, desktop icons, wallpaper (picture or video) |
| Speed & protection | Performance profile (Eco / Balanced / Ultra), keep ESO apps in memory, Defender, firewall |
| Done | Summary + main shortcuts. **Get started** saves everything. It asks for your password once, and only if you changed language, time zone or keyboard |

**Skip setup** keeps the defaults. Run it again at any time: Start → **ESO Setup**, or `WIN+R` → `eso-setup`.

### 4.2 Connect to the internet

Click the network icon on the taskbar (or `WIN+A`) → pick your Wi-Fi → enter the password. Wired and VM networks
connect by themselves.

### 4.3 Update once

Start → **ESO Store** → **Updates** → **Update all** (or `WIN+R` → `update`).

---

## 5. The desktop

### Start menu

Tap the **Windows key** (or click the ESO button on the taskbar, or `CTRL+Esc`).

- **Pinned** apps at the top, **All apps ›** for the full alphabetical list.
- Just start typing to search apps, settings and files.
- Your name at the bottom opens account settings, and the power button offers Lock, Sleep, Sign out, Restart and Shut down.
- Position (bottom center, bottom left, top left, top center, screen center) and shape (roundness) are set in
  **Settings → Personalize → Start menu**.

### Taskbar

Start button, pinned apps, then **one button per open window**, and on the right: network, volume, battery, clock and
power.

- **Click** a window button to bring that window to the front. Click it again to minimize it.
- The focused window is underlined. Minimized windows are dimmed.
- **Middle-click** closes the window.
- **Right-click** opens Restore / Minimize / Maximize / Always on top / Close. **Auto-hide** (Settings → Personalize → Taskbar) slides it away with an animation;
touch the screen edge to bring it back. It can sit at the bottom or top. `WIN+W` hides or shows it at once.

### Windows: title bars, resize, snap, always on top

Every window has a Windows 11-style title bar with the app icon, the title and **—  □  ✕** on the right. The ✕ turns red
under the mouse.

| Do this | What happens |
|---|---|
| Click **—** / **□** / **✕** | Minimize / maximize (the icon becomes ❐ "restore") / close |
| **Double-click the title bar** | Maximize (full screen above the taskbar). Double-click again = back to the previous size |
| Drag the title bar | Move the window. Windows overlap freely; the one you click comes to the front |
| Drag to the **left or right screen edge** | Snap to that half of the screen (`WIN+←` / `WIN+→` do the same) |
| Drag to the **top edge** | Maximize |
| Drag **any edge or corner** | Resize |
| **Right-click the title bar**, or `ALT+Space` | Window menu: Maximize, Minimize, Move, Resize, **Always on Top**, Fullscreen, Close |
| `WIN+CTRL+T` (or `WIN+T`) | **Always on top** on/off: the window stays above all others. A notification confirms it |
| `WIN` + drag inside a window | Move it from anywhere (`WIN` + right-drag resizes) |
| `F11` (in most apps) · `WIN+F` | Real full screen, no title bar or taskbar |

Maximized windows stop above the taskbar, so it is never covered, unless the taskbar is set to auto-hide.

Prefer the old side-by-side tiling? Settings → Personalize → **Session** → *Window style: Tiling (i3)*, then sign out and
back in.

### Desktop icons

**This PC**, **User** (your home folder), **Network** and **Recycle Bin**, which shows full or empty. Double-click to open.
Files and folders you save in the *Desktop* folder show up here too.

### Right-click menu (context menu)

- **On the desktop:** View (large / medium / small icons, show desktop icons), Refresh, New → Folder / Text document,
  Open in Matrix, Open Desktop folder, Change wallpaper…, Display settings, Personalize, Task Manager, Settings.
- **On an icon:** Open, Open with…, Open in Matrix, Rename…, Copy path, Move to Recycle Bin, Properties.
  The Recycle Bin also has **Empty Recycle Bin**.
- **In Files** (Thunar) and in apps: the usual cut / copy / paste / rename / properties menus.

### Notifications

They appear at the top right. `WIN+N` shows the recent ones again. Game mode silences them.

---

## Keyboard shortcuts

ESO uses **the same shortcuts as Windows 11**. `WIN` is the Windows key. `WIN+F1` shows this list on screen.

### Windows 11 shortcuts

| Keys | What it does |
|---|---|
| `WIN` (tap) · `CTRL+Esc` | Start menu |
| `WIN+R` | **Run**: open any app, command, folder, file or web address |
| `WIN+X` | Quick links menu (Installed apps, Task Manager, Settings, Matrix, Files, shut down…) |
| `CTRL+ALT+Del` | Security screen: Lock, Sign out, Change a password, Task Manager |
| `CTRL+SHIFT+Esc` | Task Manager |
| `WIN+E` | File Explorer (Files) |
| `WIN+I` | Settings |
| `WIN+A` | Quick settings (Wi-Fi, Bluetooth, volume, brightness, **scale**, performance profile) |
| `WIN+S` · `WIN+Q` | Search |
| `WIN+L` | Lock |
| `WIN+D` | Show the desktop (press again to get the windows back) |
| `WIN+M` | Minimize all · `WIN+SHIFT+M` brings the minimized windows back |
| `ALT+Tab` | Switch windows: hold ALT, press Tab to move, release to pick. A quick tap = previous window |
| `ALT+SHIFT+Tab` | Switch windows backwards |
| `WIN+Tab` | Task view (all windows) |
| `ALT+F4` | Close the window |
| `WIN+↑` | Maximize (again = restore) |
| `WIN+↓` | Restore a maximized window, otherwise minimize |
| `WIN+←` / `WIN+→` | Snap the window to the left / right half |
| `WIN+CTRL+T` | **Always on top** on/off (like PowerToys) |
| `ALT+Space` | Window menu (maximize, minimize, move, resize, always on top, close) |
| `WIN+SHIFT+←` / `→` | Move the window to the other monitor |
| `WIN+1` … `WIN+8` | Open or switch to the taskbar app in that position |
| `WIN+CTRL+D` | New virtual desktop |
| `WIN+CTRL+←` / `→` | Previous / next virtual desktop |
| `WIN+CTRL+F4` | Close the virtual desktop |
| `WIN+V` | Clipboard history |
| `WIN+.` · `WIN+;` | Emoji and symbols |
| `WIN+N` | Show recent notifications again |
| `WIN+P` | Project: PC screen only / Duplicate / Extend / Second screen only |
| `WIN+Space` | Next keyboard layout |
| `WIN+SHIFT+S` · `PrtSc` | Screenshot of a region |
| `WIN+PrtSc` · `SHIFT+PrtSc` | Screenshot of the whole screen (saved in *Pictures/Screenshots*) |
| `WIN+G` | Game mode on/off |
| `WIN+ALT+D` | Date and time |
| `WIN+U` | Personalize / accessibility |
| `WIN+Pause` | System information |
| `WIN+CTRL+SHIFT+B` | Restart the graphics (compositor + taskbar) if the screen misbehaves |

### ESO extras

| Keys | What it does |
|---|---|
| `WIN+Enter` | Matrix terminal (`+SHIFT` = floating window). Inside Matrix: `CTRL+SHIFT+T` tab, `ALT+SHIFT+=` split, `CTRL+SHIFT+3` PowerShell, `CTRL+SHIFT+4` Ubuntu |
| `WIN+B` | ESO Browser |
| `WIN+F` | Full screen on/off |
| `WIN+SHIFT+Q` | Close the window |
| `WIN+CTRL+1…9` | Go to virtual desktop 1–9 (`WIN+SHIFT+1…9` moves the window there) |
| `WIN+T` | Always on top on/off (same as `WIN+CTRL+T`) |
| `ALT+F7` / `ALT+F8` | Move / resize the window with the arrow keys (Enter to finish, Esc to cancel) |
| `WIN+W` | Show / hide the taskbar |
| `WIN+SHIFT+P` | Performance profile menu |
| `WIN+SHIFT+W` | Reload the wallpaper |
| `WIN+SHIFT+R` | Reload the shortcuts and restart the window manager (windows stay open) |
| `WIN+SHIFT+D` | Quick app launcher (keyboard only) |
| `WIN+CTRL+Esc` | System monitor (btop) |
| `WIN+Esc` | Power menu |
| `WIN+F1` | This list |

In apps the usual keys work: `CTRL+C / V / X / Z / A / S / F`, `CTRL+T` / `CTRL+W` tabs in the browser, `F2` rename
in Files, `F5` refresh, `F11` fullscreen in the browser.

---

## 7. Run (WIN+R)

The Windows Run box, with more features:

- Type **any installed app** by name ("fire", "store", "gimp"…). It completes as you type and shows a list of every
  matching app with its icon. Arrow keys + Enter, or click.
- Type a **command**, e.g. `htop`, `ping 8.8.8.8`. Commands that print something open in Matrix.
- Type a **folder or file**: `~/Downloads`, `/etc`, `~/Documents/notes.txt`.
- Type a **web address**: `github.com`, `https://…`.
- **Browse…** picks a program or file.
- It remembers what you ran (history is in `~/.config/eso/run-history`).
- Unknown name → "ESO can't find 'xyz'. Make sure you typed the name correctly, and then try again." like Windows.

**Windows names work too:**

| Type | Opens |
|---|---|
| `cmd`, `wt`, `terminal` | Matrix |
| `powershell`, `pwsh` · `wsl`, `ubuntu` · `arch` · `fedora` | Matrix with the PowerShell · Ubuntu · Arch · Fedora profile |
| `explorer`, `this pc` | Files |
| `notepad` · `calc` · `mspaint` | Text editor (Mousepad) · Calculator (Galculator) · Paint (Pinta, if installed) |
| `taskmgr` · `resmon` / `perfmon` · `msconfig` · `services.msc` | Task Manager · its Performance tab · Startup apps · Background apps |
| `control`, `settings`, `winver`, `msinfo32`, `sysdm.cpl` | Settings → System |
| `desk.cpl` · `ncpa.cpl` · `timedate.cpl` / `intl.cpl` · `main.cpl` · `bthprops.cpl` | Display · Network · Time & region · Mouse/Personalize · Bluetooth |
| `appwiz.cpl` · `ms-settings:appsfeatures` | Installed apps |
| `ms-settings:display`, `ms-settings:bluetooth`, `ms-settings:windowsupdate`… | The matching Settings page |
| `firewall.cpl`, `windowsdefender:` | ESO Defender |
| `ms-windows-store:` | ESO Store |
| `msedge`, `chrome` | ESO Browser |
| `diskmgmt.msc` | Disks |
| `mmsys.cpl`, `sndvol` | Sound |
| `eventvwr` · `ipconfig` · `systeminfo` | System log · network addresses · system info (in Matrix) |
| `shutdown`, `logoff` · `lock` | Security screen · Lock |
| `%userprofile%`, `%appdata%`, `%temp%`, `shell:startup`, `shell:downloads`, `shell:recyclebinfolder` | The matching folder |

---

## 8. WIN+X, Quick settings, CTRL+ALT+Del, ALT+Tab

- **WIN+X**: the power-user menu, with Installed apps, Power options, System, Disk management, Network connections, Event viewer,
  Matrix (terminal), Matrix (admin), Task Manager, Settings, File Explorer, Search, Run, Shut down or sign out, and Desktop.
- **WIN+A (Quick settings)**: Wi-Fi, Bluetooth, Airplane mode, Game mode, Do not disturb and taskbar auto-hide tiles, volume
  and brightness sliders, **Scale 80 / 100 / 125 / 150 %** (one click fixes a too-big screen), and the performance
  profile. Press `WIN+A` again or `Esc` to close.
- **CTRL+ALT+Del**: a full-screen security screen with Lock, Sign out, Change a password, Task Manager and Cancel.
- **ALT+Tab**: a row of app icons with the window title, most recently used first. Hold `ALT`, tap `Tab` to move
  (`SHIFT` goes back), and release to switch. Minimized windows are listed too and come back when picked. `WIN+Tab`
  shows a searchable list of all windows.

---

## 9. The ESO apps

Every ESO app is a native desktop program with windows, buttons, menus and icons. They open in well under a second.
With 4 GB RAM or more they stay ready in memory and re-open in about 60 ms.

### Matrix: one terminal for every shell (`WIN+Enter`, or `cmd` in Run)

Matrix is ESO's only terminal. Like Windows Terminal, it puts all your command lines in **one window with tabs
and split panes**. It is **drawn on the CPU** (GTK + VTE, OpenGL off), so it needs no graphics card: it is just as
fast in a VM, on an old laptop without a GPU, or on a gaming PC. One Matrix engine serves every window, so a new
window opens in about 50 ms once the engine is running. On PCs with 4 GB of RAM or more the engine starts with the
desktop; on smaller PCs it starts on demand (about 0.3 s) and quits when you close the last window, which saves
about 45 MB.

**Profiles** (the **⌄** button next to **+**, `CTRL+SHIFT+Space`, or `CTRL+SHIFT+1…9`):

| # | Profile | What it is |
|---|---|---|
| 1 | **Matrix** | zsh with suggestions, syntax colours and the starship prompt (the default) |
| 2 | **Bash** | plain GNU Bash |
| 3 | **PowerShell** | Microsoft PowerShell 7.6 (`pwsh`), included in ESO OS. Blue, like on Windows |
| 4 | **Ubuntu** | a real Ubuntu LTS userland in a light container (podman + distrobox), sharing your home folder. It is like WSL on Windows |
| 5 | **Arch Linux** | Arch in a container: `pacman`, and AUR helpers if you install them |
| 6 | **Fedora** | Fedora in a container: `dnf` |
| 7 | **Alpine** | tiny Alpine Linux in a container: `apk` |
| 8 | **Command Prompt** | Windows `cmd.exe` through Wine (Matrix offers to install Wine the first time) |
| 9 | **Administrator** | a root shell (`sudo -i`, asks for your password, red-tinted background) |
| – | **Python** | the Python 3 interactive shell |
| – | **SSH** | asks for `user@host`, then connects |
| – | **Your own** | Matrix settings → Profiles → give it a name and a command (e.g. `node`, `htop`, `ssh me@server`) |

- **The container profiles** (Ubuntu, Arch, Fedora, Alpine) download their system once the first time you open them.
  That needs internet and takes about 30–120 MB and 1–2 minutes. After that they open in about a second. Programs you
  install inside (e.g. `sudo apt install nodejs` in Ubuntu) stay inside that container; your files are the same everywhere.
  Remove one with `distrobox rm eso-ubuntu` (or `eso-arch`, `eso-fedora`, `eso-alpine`).
- **Tabs:** `CTRL+SHIFT+T` new tab, `CTRL+SHIFT+D` duplicate, `CTRL+SHIFT+W` close, `CTRL+Tab` next,
  `CTRL+ALT+1…9` jump to a tab, and you can drag tabs to reorder them.
- **Split panes:** `ALT+SHIFT+=` side by side, `ALT+SHIFT+-` one above the other, `ALT+SHIFT+D` split the long side,
  `ALT+Arrow keys` move between panes.
- **Copy and paste like Windows:** `CTRL+C` copies when text is selected (without a selection it stops the running program),
  `CTRL+V` pastes. `CTRL+SHIFT+C / V` always copy / paste.
- **Find:** `CTRL+SHIFT+F`. **Zoom:** `CTRL+=`, `CTRL+-`, `CTRL+0` or `CTRL`+mouse wheel. **Full screen:** `F11`.
- **Links:** `CTRL`+click opens them.
- **Right-click menu:** Copy, Paste, Select all, Find, Split right / down, New tab ▸ (any profile),
  Open this folder in Files, Clear, Settings, Close pane.
- **Matrix settings** (`CTRL+,`, or `eso-matrix --settings`): default profile, colour scheme (ESO, Matrix green,
  Campbell, PowerShell, Ubuntu, One Half Light), font and size, cursor style and blink, history length, the
  Ctrl+C / Ctrl+V behaviour, copy-on-select, and custom profiles. Saved in `~/.config/eso/matrix.json`.
- **From Run (`WIN+R`):** `cmd` / `wt` / `terminal` opens Matrix; `powershell` / `pwsh` opens PowerShell;
  `wsl` / `ubuntu` opens Ubuntu; `arch`, `fedora`, `alpine`, `bash`, `python`, `ssh` open their profiles.
  **Run as administrator** opens the Administrator profile.
- **From the command line:** `eso-matrix -p powershell`, `eso-matrix --tab -p ubuntu`, `eso-matrix -d ~/Projects`,
  `eso-matrix --hold -- make`, `eso-matrix --list-profiles`.
- **Admin commands** in any Linux profile: type `sudo` in front, e.g. `sudo apt install gimp`.
- A small system status card shows once per sign-in (turn it off with `ESO_DIAG=0`).

### Files (`WIN+E`)

Thunar with thumbnails, tabs (`CTRL+T`), archive support (right-click → Extract here / Create archive), USB drives
and phones in the side bar, and the Recycle Bin. **This PC** on the desktop opens it too.

### ESO Browser (`WIN+B`)

WebKit engine, tabs, private windows, a built-in **ad and tracker blocker**, bookmarks,
history (`CTRL+H`), downloads, dev tools (`F12`), zoom (`CTRL +/-`), and a **memory saver** that puts idle tabs to sleep.
Firefox ESR stays installed for sites that need it. Choose the default with `ESO_BROWSER=eso|firefox|chromium` in
`eso.conf`. The first start takes a few seconds longer while the blocker compiles its lists.

### ESO Store

| Tab | What it does |
|---|---|
| **Discover** | Search and install apps from Debian (70 000+ packages) and **Flathub** (thousands of desktop apps: Discord, Spotify, VS Code, OBS, GIMP, Blender, LibreOffice, Zoom…). Featured: Steam, Heroic (Epic Games), Lutris, ProtonUp-Qt |
| **Installed** | Everything installed, with **Uninstall** |
| **Updates** | System and app updates, **Update all** |
| **Install from file** | **Unknown sources**: install `.deb`, `.flatpak`, `.flatpakref` and `.AppImage` files you downloaded from any website |

**Unknown sources** are off by default. Turn them on in Store → **Store settings** or Settings → Privacy & security → *Allow apps from unknown sources* (`ESO_UNKNOWN_SOURCES=1` in `eso.conf`). ESO shows a
warning before each install, because apps from unknown websites are not checked by anyone. The Defender scans them.
You can also double-click a downloaded `.deb` or `.AppImage` in Files.

Flathub apps (Steam, Discord, VS Code…) install for your user only, so no password is needed. The Store adds the
Flathub source for your user automatically. ESO 2.2 only had it system-wide, which caused *"error: No remote refs found for
'flathub'"*. Fixed in 2.3. Manual fix on 2.2:
`flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo`.

### ESO Settings (`WIN+I`)

| Page | Contents |
|---|---|
| System | Overview, processor, memory, graphics, storage, ESO version |
| Display | Monitors and resolution (automatic), refresh rate, **scale 80–300 %**, brightness, night light |
| Network | Status, Wi-Fi networks (scan, connect), wired connections |
| Bluetooth | Turn on, scan, pair, connect, forget devices |
| Personalize | Wallpaper (picture or **live video**), taskbar (auto-hide, top/bottom), Start menu position and shape, desktop icons, **mouse cursor** theme and size |
| Apps | Manage installed apps, default apps (browser, mail, music, video, pictures, files), startup apps |
| Time & language | Time zone, automatic time, 24-hour clock, **system language**, **regional format**, keyboard layout |
| Users | Your account, password, all users |
| Performance | Eco / Balanced / Ultra, game mode, power profile |
| Updates | Check and install updates |
| Privacy & security | ESO Defender, **allow apps from unknown sources**, background apps, Flatpak app permissions |

**Mouse cursor:** Settings → Personalize → Cursor → pick any installed theme and size. To add more cursors, download one
(e.g. from gnome-look.org), extract it into `~/.icons/`, and it appears in the list.

### ESO Task Manager (`CTRL+SHIFT+Esc`)

| Tab | What it does |
|---|---|
| **Processes** | Apps, Background processes and System processes with CPU, RAM, disk and network use. Right-click → **End task**, End process tree, priority, open file location |
| **Performance** | Live graphs for CPU (per core), memory, disk, network and GPU |
| **Startup apps** | Turn apps that start with ESO on or off |
| **Background apps** | **You decide which apps may keep running in the background**: allowed apps keep working after you close their window, denied apps are fully stopped |

### ESO Defender (Start → ESO Defender, or `defender` in Run)

It works like **white blood cells**:

1. **Cell bank**: on the first start and after every update, ESO stores fingerprints and spare copies of the 2 000+ files
   needed to start and sign in (kernel, systemd, libraries, login, desktop). It also keeps a spare kernel with its own boot entry.
2. **Regeneration**: if a virus deletes or damages those files, the Defender puts back the original copy
   (in about 35 ms). It does this even **before the OS starts**, from the boot image, so a system whose files were wiped still boots.
   Anything else is rebuilt from the original Debian packages.
3. **Memory**: every attack is remembered: the fingerprint of the bad file, where it came from and what ran it.
   The next time it appears, it is quarantined immediately and its process is stopped before it can act.
4. **Scanning**: quick and full scans, learned threats, miners and rootkits, suspicious autostart entries, files that no
   package owns, and a check of every OS file against Debian's checksums. It uses ClamAV too when installed.
5. **Firewall**: incoming connections blocked, outgoing allowed.
6. **Quarantine**: restore or delete anything it caught. Alerts for new startup entries let you **Allow** or **Block**.

It uses about 15 MB of RAM and 0 % CPU while nothing happens.
**If the system does not start:** hold **Esc** at power-on → **ESO Defender recovery**.
Command line: `sudo eso-defender scan quick|full`, `heal`, `quarantine list`, `firewall status`.

### ESO Lock (`WIN+L`)

A curtain with a large clock, date, media controls (play/pause, next), and battery and network status over your wallpaper. **Just start typing** to unlock (no click needed). Wrong passwords wait a little longer each
time, and repeated failures lock the screen for a while. If the lock screen app ever crashed, a backup lock takes
over at once, so your session is never left open. It also locks when the PC wakes from sleep.

---

## 10. Personalize

### Wallpaper: pictures or live video

Right-click the desktop → **Change wallpaper…**, or Settings → Personalize → Wallpaper.

- **Pictures:** JPG, PNG, WebP of any size. ESO keeps only the size your screen needs in memory.
- **Live wallpapers:** MP4, WebM or MKV **up to 4K**, looped and muted. They use the GPU's video decoder when there is
  one. In the Eco profile they run at 24 fps to save CPU.
  Free 4K loops: search "4K loop" on Pexels, Pixabay or Mixkit.

### Start menu shape and position

Settings → Personalize → **Start menu**: position (bottom center, bottom left, top left, top center, screen center) and
**corner roundness** from square to fully rounded (0–32 px).

### Taskbar

Settings → Personalize → **Taskbar**: auto-hide with slide animation, bottom or top. Both apply at once in ESO Desktop.
With auto-hide on, maximized windows use the whole screen. With it off, they stop above the taskbar.

### Scale and resolution

- The resolution is **automatic**: ESO reads what your monitor supports and uses its native mode. In VMs it picks the
  largest mode up to 1920×1080 and follows the window size when guest tools are present (QEMU/SPICE, VMware).
- The scale is **100 %** by default. Change it with **WIN+A → Scale** (one click), Settings → Display, or ESO Setup.
  80 % gives more space. Use 125–150 % on 4K and HiDPI laptop screens.

### Mouse cursor

See [ESO Settings](#eso-settings-wini). Cursor size follows the scale automatically.

---

## 11. Gaming

1. ESO Store → **Steam** → Install. Sign in. For Windows games: Steam → Settings → Compatibility → **Enable Steam Play
   for all other titles** (Proton).
2. **Epic Games**: ESO Store → **Heroic Games Launcher** → sign in with your Epic account (GOG and Amazon work too).
   Your Epic library installs and runs through Proton/Wine.
3. **Lutris** for other stores (Battle.net, EA, Ubisoft) and emulators; **ProtonUp-Qt** installs Proton-GE for extra
   compatibility.
4. Press **WIN+G** for game mode: effects off, VRR/tearing allowed, performance power profile, notifications muted.
   Games also get the lowest-latency path automatically.

**Good to know:** check a game on [protondb.com](https://www.protondb.com) before buying it. Most Windows games run, but
a few online games whose anti-cheat blocks Linux do not (e.g. Valorant, Fortnite, some Call of Duty titles). NVIDIA
cards: install the NVIDIA driver with `sudo apt install nvidia-driver` in Matrix, then restart. AMD and Intel work out of the box.

---

## 12. Speed

### Performance profiles (`WIN+SHIFT+P`, WIN+A, Settings → Performance, or ESO Setup)

| Profile | Effects | Best for |
|---|---|---|
| **Eco** (automatic in VMs and with less than 4 GB RAM) | No blur, shadows or animations | 1–2 GB RAM, old CPUs, VMs, battery |
| **Balanced** (default on real PCs) | Light blur, soft shadows, quick animations | Most laptops and desktops |
| **Ultra** | Every effect | Gaming PCs with a real GPU |
| **Game mode** (`WIN+G`) | Everything off, tearing/VRR allowed, performance power profile | Maximum FPS |

### Two sessions

- **ESO Desktop (default, X11 + xfwm4 + picom)** runs everywhere: VMs, old laptops, gaming PCs. You get Windows-style windows
  (title bars, minimize/maximize/close, resize, snap, always on top) and no GPU is needed. The window manager adds about 13 MB.
- **ESO Tiling (Hyprland, Wayland)** is opt-in for keyboard-tiling fans with a real GPU. Windows tile automatically,
  with blur and animations and no title bars.

Switch in Settings → Personalize → **Session** (applies at the next sign-in), or from the login screen's session menu.
If Hyprland fails to start, ESO Desktop starts instead. Inside ESO Desktop you can also choose *Tiling (i3)* as the window style.

### What ESO already does for speed

A full-preemption kernel, zram swap, small disk-write buffers, BBR networking, the right I/O scheduler per disk,
earlyoom (so a runaway app is stopped instead of freezing the PC), a 5-second shutdown limit, a 1-second boot menu,
services that delay boot turned off, background jobs (Defender, updates) at idle priority, apps that stay in memory
when there is RAM to spare, and a live USB compressed with zstd for faster reading.

### Tips

- **In a VM, turn on hardware virtualisation.** This matters more than anything else (see [section 2](#2-run-it-in-a-virtual-machine)).
- Close apps you don't need, or stop them from running in the background: Task Manager → **Background apps**.
- Turn off startup apps you don't need: Task Manager → **Startup apps**.
- Use Eco on weak PCs.
- The first start after installing is slightly slower while the Defender builds its file bank in the background (about a minute).
- Typical numbers: idle RAM about 350–420 MB, idle CPU about 0–1 %. Apps open in 0.1–0.5 s (ESO apps kept in memory: ~60 ms).
  Keys and clicks respond on the next screen refresh (16.7 ms at 60 Hz, 4.2 ms at 240 Hz).

---

## 13. Troubleshooting

### 13.1 Everything is too big (200 %)

The scale ESO uses is 100 %. If it still looks doubled, something outside ESO is enlarging it:

1. **VirtualBox on a Windows PC with display scaling (150–200 %):** VirtualBox enlarges the whole VM screen.
   Fix: VM window → **View → Virtual Screen 1 → Scale to 100 %**; VM Settings → Display → **Scale Factor 100 %**;
   and try toggling **View → Use Unscaled HiDPI Output**.
2. **VMware:** VM Settings → Display → clear **Automatically adjust user interface size**, and turn off **Stretch mode**.
3. **Hyper-V:** View → Zoom level → 100 %; set the resolution with `Set-VMVideo` (section 2).
4. **Low resolution:** a VM that runs at 800×600 or 1024×768 makes everything look huge. ESO picks the largest mode up to
   1920×1080, but you can choose one yourself in Settings → Display.
5. **Inside ESO:** **WIN+A → Scale → 100 %** or **80 %**. Or in Matrix: `eso-display scale 1` (or `0.8`).
6. Still using **ESO 1.0.0**? Download 2.3.0; 1.0.0 had this problem.

### 13.2 It feels slow

1. VM: hardware virtualisation on, 2+ CPUs, 2+ GB RAM, 3D acceleration off in VirtualBox (section 2).
   In VirtualBox, "Paravirtualization: KVM" and "Nested paging" help.
2. Check that the light session is running on weak hardware: `WIN+R` → `systeminfo`, or the login-screen session menu → **ESO Desktop**.
3. `WIN+SHIFT+P` → **Eco**.
4. Task Manager (`CTRL+SHIFT+Esc`) → sort by CPU or Memory → **End task** on whatever is heavy.
5. The live USB is slower than an installed system (USB 2 sticks especially). Install it for full speed.

### 13.3 No internet

WIN+A → Wi-Fi on → pick the network. VM: set the network adapter to **NAT**. Wi-Fi card not found: some cards need
firmware. Plug in a cable or use phone tethering, then `sudo apt install firmware-linux-nonfree firmware-iwlwifi`
(Intel) or `firmware-realtek` / `firmware-atheros`, and restart.

### 13.4 Black screen or it doesn't start

- **USB stick:** check the SHA-256, rewrite it in DD mode (Rufus) or use Ventoy, and try another USB port.
  If the screen stays black, it is usually the graphics card: at the boot entry press `e` (UEFI) or `Tab` (BIOS), add `nomodeset` to
  the line that starts with `linux`, then press `F10` / `Enter`.
- **Installed system:** hold **Esc** at power-on → **Advanced options** (older kernel) or **ESO Defender recovery**.
- **Graphics glitch after sign-in:** `WIN+CTRL+SHIFT+B`, or choose **ESO Desktop** on the login screen.
- **An app froze:** `ALT+F4`, `WIN+SHIFT+Q`, or Task Manager → End task.

### 13.5 Forgotten password

Hold Esc at power-on → Advanced options → **recovery mode** → **root** → `passwd yourname` → `reboot`.
(VM images: the default is `eso` / `eso`.)

### 13.6 A shortcut does nothing

Another app may have grabbed the key, or you are in a fullscreen game. `WIN+SHIFT+R` reloads the shortcuts (`~/.config/sxhkd/sxhkdrc`) and the window manager.
`WIN+F1` lists every shortcut.

### 13.7 Report a problem

In Matrix, `eso-diag --full` prints a system status card (CPU, GPU, RAM, disk, session, ESO version), and
`journalctl -b -p warning` shows this boot's warnings. Copy both into your bug report.

---

## 14. Updating

- **ESO Store → Updates → Update all**, or in Matrix: `sudo apt update && sudo apt full-upgrade`.
- After each update the Defender refreshes its file bank automatically (idle priority).
- Moving to a new ESO release: install it over the old one with the installer (Manual partitioning → reuse the partition
  without formatting `/home`), or reinstall and restore your files.

---

## 15. Settings file reference

Per-user settings live in `~/.config/eso/eso.conf` (ESO Setup and Settings write it; you can edit it in any text editor):

| Key | Values | Meaning |
|---|---|---|
| `ESO_SCALE` | `0.8`, `1`, `1.25`, `1.5`, `2` | UI scale (1 = 100 %) |
| `ESO_AUTO_RES` | `1` / `0` | Automatic resolution |
| `ESO_TASKBAR_AUTOHIDE` | `1` / `0` | Auto-hide the taskbar |
| `ESO_TASKBAR_POS` | `bottom` / `top` | Taskbar position |
| `ESO_START_POS` | `bottom-center`, `bottom-left`, `top-left`, `top-center`, `center` | Start menu position |
| `ESO_START_RADIUS` | `0`–`32` | Start menu corner roundness |
| `ESO_DESKTOP_ICONS` | `1` / `0` | Desktop icons |
| `ESO_ICON_SIZE` | `32`, `48`, `64` | Desktop icon size |
| `ESO_APPS_RESIDENT` | `auto`, `1`, `0` | Keep ESO apps (and the Matrix engine) in memory |
| `ESO_BROWSER` | `eso`, `firefox`, `chromium` | Default browser |
| `ESO_UNKNOWN_SOURCES` | `1` / `0` | Allow installing apps from unknown sources |
| `ESO_KB_LAYOUT` | e.g. `us`, `fr`, `us,ara` | Keyboard layout(s) applied at sign-in |
| `ESO_DIAG` | `1` / `0` | Status card in Matrix |

Other useful places: `~/.config/eso/run-history` (Run history), `/usr/share/doc/eso/tutorial.md` (this guide),
`/var/lib/eso-defender/` (Defender bank, quarantine and memory).

---

## 16. FAQ and honest limits

**Is ESO a new OS or a Debian skin?** ESO OS is its own distribution built on Debian's base: its own desktop, apps, session,
installer, boot setup, speed tuning and security (Defender). It uses Debian's kernel and packages underneath, like
Ubuntu, Linux Mint and Pop!_OS do. That is how it gets 70 000+ packages, drivers and security updates on day one.

**Can it be separated from Debian?** Yes, step by step. Its own name and branding are done. Next come its own package
repository (ESO updates arrive through it) and a tuned ESO kernel built from the Linux source. Rebuilding every package
itself is possible but takes a large team, and it gives users nothing that Debian's base doesn't already provide.

**Its own kernel?** A *tuned* kernel built from Linux (like Zen, Liquorix, XanMod) is realistic and planned. A kernel
written from scratch would need thousands of developers and decades of driver work (Linux has 30+ years) and would
support far fewer devices.

**Its own BIOS?** No. The BIOS/UEFI is firmware stored on the motherboard, written by the PC maker. No operating system
ships its own, and Windows and macOS don't either. ESO supports both BIOS and UEFI, including Secure Boot.

**0.01 ms response?** Not physically possible on any OS. A 60 Hz screen shows a new picture every 16.7 ms (240 Hz: 4.2 ms),
keyboards and mice report every 1–8 ms, and storage takes time to read. ESO answers on the next frame and keeps
background work at idle priority. Booting takes seconds, shutting down 1–5 s.

**A browser under 10 MB of RAM?** No engine that can run today's websites fits in 10 MB. Websites alone often use
50–300 MB. ESO Browser is light for a real browser: it blocks ads and trackers and puts idle tabs to sleep.

**Does it run Windows and Mac apps?** Many Windows apps and most Windows games run through Wine/Proton (Steam, Heroic,
Lutris, Bottles from the Store). Apps with kernel anti-cheat or deep Windows hooks (some online games, Adobe CC) do not.
macOS apps can't run on any non-Apple OS. For most of them there is a Linux version or a good alternative in the Store
(LibreOffice, GIMP, Krita, DaVinci Resolve, Blender, OBS, VS Code, Discord, Spotify…).

**Under 400 MB RAM?** The idle desktop uses about 350–420 MB (less in Eco). Apps you open add their own memory,
as on every OS.

**Is my data sent anywhere?** No. ESO has no telemetry. Only the time zone detection in ESO Setup asks a public service,
and only if you click **Detect from the internet**.

**Which PCs does it run on?** Any 64-bit Intel or AMD CPU (about 2008 and newer), 1 GB to 256 GB+ RAM, with or without a
GPU (Intel, AMD, NVIDIA), BIOS or UEFI, and VMs (VirtualBox, VMware, Hyper-V, QEMU/KVM, Proxmox).
ARM PCs and Apple-silicon Macs are not supported yet.

---

*ESO OS 2.3.0 · Debian 13 base · Linux 7.1 · Mesa 26.1 · Hyprland 0.55 · this guide ships with the OS at
`/usr/share/doc/eso/tutorial.md`.*