Phoebus OS Help

A practical, offline guide to the desktop, packages, recovery, and shortcuts.

Getting started

Phoebus is a Gentoo workstation with the Mango Wayland compositor, DankMaterialShell (DMS), Portage, Flatpak, and Nix. The system remains usable offline after installation. The terminal tool sys is the shared interface for package management and system administration.

Open Phoebus Welcome from the app launcher or press Super+Shift+W. Open the original DMS Welcome from the launcher or press Super+Alt+W. Press Super+F1 to reopen this guide.

“Super” is usually the Windows or Command key. Settings and Welcome are regular windows; the Assistant is a floating scratchpad.

Desktop controls

The top bar holds the app launcher and workspaces on the left, clock and optional weather in the center, and system controls on the right. Click the right side for clipboard, process list, notifications, volume, connectivity, and quick settings. Click the clock for the calendar. Some controls appear only when the corresponding device or service exists.

Open the app launcher with Super+Space or Super+P. Type an app or command and press Enter. Press Escape to dismiss a panel. Open DMS Settings from the launcher or Super+Ctrl+,.

Keybinding cheat sheet

KeysAction
Super+Shift+EnterTerminal
Super+Space or Super+PApp launcher
Super+AShow or hide Phoebus Assistant
Super+UPhoebus Updates
Super+F1Phoebus Help
Super+Shift+W / Super+Alt+WPhoebus Welcome / DMS Welcome
Super+Ctrl+,DMS Settings
Super+V / Super+NClipboard history / notifications
Super+Ctrl+MProcess list
Super+Alt+LLock screen
Super+1…9Switch workspace
Super+Shift+1…9Move focused window to workspace
Super+TabPrevious workspace
Super+J/K or arrow keysFocus another window
Super+Shift+J/K or arrow keysSwap focused window
Super+H/LShrink / grow master area
Super+I/DAdd / remove a master window
Super+EnterSwap focused window with master
Super+T/MTile / monocle layout
Super+FToggle fullscreen
Super+Shift+SpaceToggle floating
Super+Shift+CClose focused window
Super+RReload Mango configuration
Super+drag left/right mouse buttonMove / resize a floating window
Super+Shift+F9…F12Switch display resolution (1024×768, 1280×768, 1440×900, 1920×1080)

Advanced bindings also include Super+Ctrl+number to add a workspace to the view, Super+Ctrl+Shift+number to toggle a window tag, Super+comma/period to focus another monitor, and Super+Shift+comma/period to move a window there. Super+Shift+E exits the desktop session.

Apps and packages

Run sys --help for the full command reference. Plain sys commands use the connected model; --legacy uses deterministic actions and works without a model. A package source flag selects exactly one lane. Operations show a review before mutation and may require administrator authentication.

sys search firefox --legacy
sys search firefox --legacy --flatpak
sys install firefox --legacy --flatpak
sys install cmatrix --legacy --nix
sys install app-editors/vim --legacy --portage
sys remove firefox --legacy --flatpak
sys updates --legacy
sudo sys apply updates --legacy
sys history --legacy

Available sources include Portage, Flatpak, Nix, Snap when snapd is installed, managed AppImages, and custom ebuilds. Search a lane first when the name is uncertain. A lane that is unavailable reports why; package management never silently switches sources. Portage, Flatpak, and other backend progress stays visible while work runs.

Assistant and models

Press Super+A to show or hide the Assistant without losing its conversation. The Assistant proposes typed system actions. Review and authenticate any change yourself; the model does not receive a root shell. Its Updates, Legacy, Alerts, and Preferences tabs give direct access to the same system capabilities. If no model is connected, use sys --legacy and the Legacy tab.

Model connection is configured through Phoebus setup or assistant preferences. Keep provider tokens in the supported secret storage; never paste them into a package request or terminal history.

Updates and recovery

Open Phoebus Updates from the launcher or press Super+U. It checks Portage, Flatpak and Snap without a model. Portage checks use your last synced repository metadata; run sudo emerge --sync to discover newly published Gentoo and GURU packages. Choose Review & Apply to open an interactive sys update in a terminal, review the exact plan and approve it. Package progress stays visible until you close the terminal. This keeps DankMaterialShell updated through Portage along with other Gentoo packages. Use Phoebus Updates for system updates; the separate updater page in DMS Settings does not manage Portage. Nix, managed AppImages and custom ebuilds have separate update paths. You can also use sys updates --legacy to inspect and sudo sys apply updates --legacy to review and apply. sys history --legacy lists recorded actions. sys undo status --legacy shows recovery state; sudo sys undo --legacy begins a reviewed undo where available. Snapshots protect high risk operations, but complete Btrfs rollback is still under development. Keep regular backups of personal files.

For boot trouble, select the known good kernel from the boot menu. Phoebus uses UEFI, LUKS2 encryption, Btrfs, and systemd; do not erase or reformat disks while diagnosing a boot issue.

Settings and displays

DMS Settings controls appearance, bar, widgets, display, input, audio, notifications, network, and session options. On a virtual machine, resize the viewer first; use the display page if the guest resolution does not follow. The resolution shortcuts above offer an immediate fallback. Wallpaper files live in ~/Pictures/Wallpapers; DMS can choose one from its Wallpaper page.

Changes to your personal Mango config live under ~/.config/mango/. The packaged defaults are copied only for a new account, so updates preserve your custom bindings.

Troubleshooting

If the bar or a panel does not appear, run dms ipc call settings focusOrToggle from a terminal to check whether DMS responds. Reopen the Assistant with Super+A. To inspect the compositor, run mmsg get all-clients in a Wayland terminal. For package errors, run the same sys command in a terminal to read its status and backend output. sys --help and dms ipc --help list current commands.

This guide is stored on the local system at /usr/share/phoebus/help/index.html and remains available without network access.