Skip to main content
After installing Otter Shell, start your own Wayland compositor. Otter Shell does not provide a user-session compositor. Installed applications are native binaries; you do not need otr or Zig to run them.
1

Launch the terminal

The terminal renders on the CPU through the shared Otter render stack. Its grid does not need a GPU.
2

Start background daemons

Start these for now:
Optional: otter-dock & or otter-taskbar & for a bottom app strip.For a permanent setup, add them to compositor autostart. See Session setup.
3

Choose settings and extensions

Choose shared colors, layout, and spacing under Theme. Use Plugins to enable installed Lua extensions and review their capabilities. UI Scripts controls supported surface scripts and their native fallback. See Configuration.
4

Open the launcher

Bind this to a compositor hotkey for daily use:
Type to search apps. Try =2+3*4 (calculator), :heart (emoji), clip (clipboard), or file invoice / grep TODO (desktop search; needs otter-search running).
5

Open the workspace overview

Bind Super, or another spare key:
The overview shows workspace cards, window tiles, search, and an app grid. See otter-overview.
6

Bind Alt-Tab

The same package ships otter-switcher:
Bind Alt-Tab to it. Each press advances the selection; releasing Alt focuses the selected window. See otter-switcher.
7

Take a screenshot

Click and drag a region. The image copies to your clipboard.
8

Try the auto-clicker

With the default config, pick a point with the crosshair, then let it click. Run toggle again to stop. See otter-clicker.
9

Create a sticky note

Bind a hotkey, for example Super+N.
10

Open the system monitor

Check CPU, memory, disk, and running processes. See otter-monitor.
11

Check the weather

Print current conditions:
For the status bar, add a weather widget in otter-bar and run:
See otter-weather and otter-bar.
Bind global hotkeys in your compositor because Wayland apps cannot grab system-wide shortcuts. For example:Hyprland (~/.config/hypr/hyprland.conf):
Sway (~/.config/sway/config):
See Keybinds for the full reference.

​
Next

Session setup

Autostart the shell daemons your desktop needs.

Status bar

Set up widgets, tray, and the launcher button.

Settings

Bar, theme, and app settings in the GUI.

Configuration

Manual config files and hot-reload behavior.