Desktop selection and session recovery

Aqueous manages windows and the desktop session. Pearl provides the bar, launcher and Settings. Choose the matching session when you log in.

Identify your desktop first

The package you install determines the login entry and configuration folder. The two Git options below share component names, so choose one.

Desktop package	Login entry	Configuration
`aqueous-desktop`	Aqueous	`~/.config/aqueous/`; Pearl selected by default
`aqueous-desktop-git`	Aqueous	Same folder; replaces stable Aqueous and starts `pearl-git`
`aqueous-git` from `packaging/arch/aqueous-git`	Aqueous-Git	`~/.config/aqueous-git/`; choose a shell yourself

These packages no longer include Welcome. The older root PKGBUILD (aqueous 1.0.5-1) still uses the Welcome flow. The Arch Pearl preset changed at 1.0.5-2.

On Arch/CachyOS, check your installed packages with:

shelly search standard --installed aqueous
shelly search standard --installed pearl

Use shelly search standard --detail aqueous-desktop (or aqueous-git) to check available packages, dependencies and conflicts before installing. Fedora’s aqueous-git RPM is a different package; follow the distribution guide.

Install the matching Pearl preset. aqueous-desktop already includes it; the separate Aqueous-Git session needs aqueous-shell-pearl-git and pearl-git.
Back up an existing session.toml, then edit it in the folder above:
```
version = 1
shell = "pearl"
```
Save your work, log out and select Aqueous or Aqueous-Git as appropriate. Changing the file takes effect at the next login.
Open a terminal and run pearlctl status, or pearlctl-git status for Git Pearl. Check that Settings opens and your keyboard layout works.

Your user session.toml overrides /etc/xdg/aqueous/session.toml, including after upgrades. Keep exactly one version and one shell field.

The separate Aqueous-Git session also accepts dms, noctalia and none. Install the matching preset before choosing another shell. With none, the launcher shortcut opens Ghostty and there is no locker. Live aqueousctl-git shell switch is retired; edit the file and log in again. See the Git packaging guide.

Older packages with Welcome

If your package includes aqueous-welcome, open it, choose a shell and review the changes. Close Welcome and start desktop starts it immediately; closing the window normally leaves the change for your next login. A failed activation restores the previous managed shell. Newer presets do not need Welcome.

Stable and Git instance paths

Item	Aqueous / replacement Git desktop	Separate Aqueous-Git desktop
Compositor	`aqueous`	`aqueous-git`
CLI	`aqueousctl`	`aqueousctl-git`
Settings helper	`aqueous-config`	`aqueous-config-git`
Configuration	`~/.config/aqueous/`	`~/.config/aqueous-git/`
Managed Pearl service	`aqueous-pearl.service`	`aqueous-git-pearl.service`

Use pearlctl-git with Git Pearl, including in the replacement desktop. Both Pearl packages share ~/.config/pearl/ preferences. A separate Aqueous-Git session does not isolate those settings or your applications.

Paths use $XDG_CONFIG_HOME when set. Run tools from the intended session’s terminal so they reach the right compositor. Helper journals are under $XDG_STATE_HOME/<instance>/config-writer. See configuration paths.

Upgrade without losing your settings

Save your work and back up the files you use. Keep a working console login or another desktop available.
Update through your distribution. On Devario, use Shelly’s Update page and the configured Devario repositories. On Arch/CachyOS, update matching components together with shelly upgrade standard. Use shelly upgrade aur for AUR packages, or shelly upgrade all for all enabled backends.
Review replacements and .pacnew files. The Pearl preset replaces retired Welcome and other-shell integration packages, but keeps those applications and their settings. Check greeter changes before your next login.
Log in again and check Pearl, Settings, keyboard input, displays and capture.

Moving from the separate Git session to the replacement Git desktop changes the config folder from aqueous-git/ to aqueous/. Merge only the settings you want; packaging does not migrate them. Review monitor and device IDs before reusing a configuration on another machine.

Recover a missing shell or failed upgrade

If Aqueous still responds, open a terminal (normally Super+Return) and check session.toml, the installed shell and its service:

systemctl --user status aqueous-pearl.service --no-pager

Use aqueous-git-pearl.service for the separate Git session. Restore your previous shell selection if needed, then log in again. A missing shell or an invalid selection leaves the session without that shell. A second, independently started shell service can cause duplicate bars or notifications.

If graphical login fails, use console or greeter recovery. For a downgrade, restore a compatible package set and its config backup; downgrading only the compositor can break versioned dependencies. Keep theme ownership records and use theme recovery before changing versions.

For freezes or a black screen, collect diagnostics first. The reported logout hard-lock still has no confirmed fix.