Aurora OS Documentation

The official documentation for the latest Aurora OS release.

This is the reference documentation for Aurora OS: how to install it, how every part of the desktop works, every setting, every keyboard shortcut, the sessions and services behind it, and what to do when something goes wrong. Use the search box (press /) or browse by topic.

Getting started

IntroductionWhat Aurora OS is, what this documentation covers and how it is organized
System requirementsThe hardware Aurora OS needs, and what works best
Get Aurora OSDownload or build the ISO, check it, and write it to a USB stick
The boot menuEvery entry of the USB stick's boot menu, and the firmware's boot keys
The live sessionUsing Aurora from the USB stick before installing it
Installing Aurora OSThe installer step by step: language, location, keyboard, disk, user, summary
First bootThe Welcome app, and the first things worth doing

The login screenThe greeter: logging in, choosing a session, restarting and shutting down
Desktop sessionsAurora (Wayfire) and Aurora Compatibility (labwc): what each is and when to use it
What happens when you log inThe session manager: environment, language, keyboard, compositor, shell and autostart, step by step
Locking, screen off and suspendWhen the screen locks, turns off and the computer sleeps, and how to change it
Shutting down, restarting, logging outThe power choices, sounds, and what happens to open apps

The desktop

The desktop at a glanceThe parts of Aurora's desktop and what each is for
Top barEvery item of the top bar, from left to right
Aurora menuThe menu behind the logo: your account, system actions and power
Control CenterVolume, brightness, networks and quick toggles, laid out like Android's quick settings
Calendar, weather and notificationsThe clock's popover: calendar, weather, notification history and Do Not Disturb
DockFavorites and open apps, windows, Launchpad, minimized windows and the Trash
Spotlight searchOne search for apps, settings, files, projects, math, conversions, emoji, clipboard, commands, the AI and the web
LaunchpadEvery app as a full-screen grid
Overview and workspacesEvery window at a glance, Show Desktop, and virtual desktops
Hot corners and gesturesCorner actions and touchpad gestures
Desktop iconsFiles on the desktop: selecting, opening, arranging, dropping
Desktop widgetsGlanceable cards on the desktop: adding, arranging, customizing, every widget and its options
Appearance and backgroundsLight and dark, accent colors, backgrounds, picture of the day, icons, fonts and Night Light

Windows

Working with windowsMoving, resizing, title bar buttons, switching, minimizing, fullscreen
Snapping and Snap LayoutsHalves, thirds and quarters, Snap Layouts, Snap Assist
Always on topKeeping a window above the others

Apps

FilesAurora's file manager: places, views, tabs, copying, archives, network folders, Quick Look and more
Task ManagerProcesses grouped by app, performance graphs, startup apps and services
The Settings appFinding your way around Settings; every page is in the Settings reference
App CenterInstalling and updating apps from Debian and Flathub
Dev HubOne-click installers for editors, languages, cloud tools, databases, containers and more, and project workspaces
Game HubGame stores, Windows games and apps, performance tools and Android apps
Terminal and command linePtyxis, the shell, the prompt, aliases, containers and developer tools
Screenshots, recording and screen toolsScreenshots, annotation, text recognition, color picker and screen recording
Clipboard history and emojiEverything you copied, pinned items, images, and the emoji picker
Quick LookPreviewing files with the space bar
Included appsEvery app installed by default

Settings reference

Every Settings page and optionEach page of the Settings app, its groups and every option, generated from Settings' source

System

Updates and restartsSecurity updates, app updates, restarts and active hours, newer kernels, Aurora's own packages
Snapshots and recoveryAutomatic system snapshots on btrfs, rolling back from the boot menu, Timeshift
BackupsBacking up your files with Backups (Déjà Dup)
Storage and Storage SenseWhat takes the disk space, one-click cleanup and automatic cleanup
Screen TimeHow long you use each app, the week as bars, and daily limits
Security and privacyFirewall, updates, encryption, fingerprint, permissions, administrator prompts and what goes online
NetworkingWi-Fi, wired, VPNs, hotspot, sharing Wi-Fi with a QR code, proxies and network tools
Sharing and your phoneNearby sharing, screen sharing, SSH, KDE Connect and network folders
Displays, Bluetooth and printersMonitors, resolution and scale, Bluetooth devices, printers and scanners
Sound and Volume MixerOutput and input devices, balance, over-amplification, each app's volume, system sounds
Power and batteryScreen blank, suspend, power button and lid, power modes, battery health and charge limit
AccessibilitySeeing, hearing, typing and pointing: zoom, screen reader, high contrast, screen keyboard and more
Languages and keyboardsChanging the language, formats, keyboard layouts and switching between them

Aurora AI

Turning on Aurora AIWhere answers come from: a model on your computer, on your network, or a cloud provider
Aurora AssistantThe floating chat: opening it, attachments, quick actions, models, collapsing
Where Aurora AI helpsSpotlight, terminal, Writing Tools, Files, screenshots, notifications, dictation, read aloud, search by meaning

Virtual machines

Virtual machinesRunning Aurora in QEMU, GNOME Boxes, virt-manager, VirtualBox and VMware
Hyper-VCreating the VM with the script, installing, checkpoints, the boot order and using the GPU for AI

Troubleshooting

TroubleshootingBlack screens, a desktop that doesn't start, missing sound or Wi-Fi, logs, System Health and resetting settings
Frequently asked questionsShort answers to common questions

Reference

Keyboard shortcutsEvery system-wide shortcut, generated from Aurora's keyboard configuration, plus the ones inside Aurora's apps
Shell commandsaurora-shell's commands, for scripts and your own shortcuts
Command-line toolsAurora's own programs and helpers
Configuration filesWhere Aurora keeps its settings, which files you can edit, and what each does
GSettings keysEvery Aurora setting key, its type, default and meaning, generated from the schema
Environment variablesWhat an Aurora session sets, and variables that change Aurora's behavior
System servicesAurora's own services and timers
GlossaryWords used in this documentation

Developing Aurora

Building AuroraRequirements, make targets, build stages and developing the desktop without an ISO
TestingThe test suites and what each checks
Translating AuroraAdding or fixing translations of Aurora's own apps
ContributingReporting problems and sending changes