Session setup

Otter Shell runs on your Wayland compositor. The metapackage installs apps; it does not configure your compositor. This page covers autostart and hotkeys. Autostart these for a working desktop:

Daemon	Required	Purpose
`otter-bar`	Recommended	Status bar, system tray, workspace indicator
`otter-wallpaper`	Recommended	Desktop background
`otter-theme-gen`	Optional	Wallpaper-reactive `theme.conf` (use with `otter-wallpaper`)
`otter-notifications`	Recommended	`notify-send` and app notifications
`otter-osd`	Recommended	Volume/brightness/lock-key overlays
`otter-idle`	Recommended	Screen lock and DPMS on idle
`otter-polkit`	Recommended	Authentication for privileged actions
`otter-clip daemon`	Optional	Clipboard history
`otter-search`	Optional	File and content search (launcher `file` / `grep` modes)
`otter-weather --watch 900 --write-cache`	Optional	Bar weather widget data
`otter-jade`	Optional	Desktop pet
`otter-transcribe`	Optional	Speech transcription (needs `otter-shell-extras`)
`otter-assist`	Optional	Local AI backend for Otter Assistant (`otter-shell-extras`)

Do not autostart one-shot apps: otter-launcher, otter-logout, otter-screenshot. Bind hotkeys instead.

Compositor autostart examples

Hyprland

Add to ~/.config/hypr/hyprland.conf:

exec-once = otter-bar
exec-once = otter-wallpaper
exec-once = otter-theme-gen
exec-once = otter-notifications
exec-once = otter-osd
exec-once = otter-idle
exec-once = otter-polkit
exec-once = otter-clip daemon
exec-once = otter-search
exec-once = otter-weather --watch 900 --write-cache
# Optional: otter-shell-extras
# exec-once = otter-assist
# exec-once = otter-transcribe

Sway

Add to ~/.config/sway/config:

exec otter-bar
exec otter-wallpaper
exec otter-theme-gen
exec otter-notifications
exec otter-osd
exec otter-idle
exec otter-polkit
exec otter-clip daemon
exec otter-weather --watch 900 --write-cache

Niri

Add to ~/.config/niri/config.kdl:

spawn-at-startup "otter-bar"
spawn-at-startup "otter-wallpaper"
spawn-at-startup "otter-theme-gen"
spawn-at-startup "otter-notifications"
spawn-at-startup "otter-osd"
spawn-at-startup "otter-idle"
spawn-at-startup "otter-polkit"
spawn-at-startup "otter-clip" "daemon"
spawn-at-startup "otter-weather" "--watch" "900" "--write-cache"

Display manager

otter-greeter is Otter Shell’s Wayland display manager:

otter-greeterd: root daemon for PAM, logind, and session launch
otter-greeter-ui: login UI on Hyprland (greeter only, not your user session)

Enable after install:

sudo systemctl enable otter-greeter.service

Config: /etc/otter-shell/otter-greeter.conf. See otter-greeter.

Session security flow

otter-idle: Detects inactivity; runs loginctl lock-session or DPMS
otter-lock: Session lockscreen via ext-session-lock-v1
otter-logout: Power menu for lock, logout, suspend, reboot, shutdown
otter-polkit: Password dialog for elevated privileges

Action	Command
Lock session	`loginctl lock-session`
Power menu	`otter-logout`

Protocol requirements

Component	Protocol / dependency
Bar, launcher, notifications, OSD, logout, lock	`zwlr_layer_shell_v1` (wlroots layer shell)
Lock screen	`ext-session-lock-v1`
Screenshot, pick, shot	`ext_image_copy_capture_v1`
Idle daemon	`ext-idle-notify-v1` (optional; compositor IPC fallbacks exist)

If something fails, check compositor protocol support first.

Next steps

After autostart, open otter-settings for bar layout, theme, and terminal fonts.

otter-settings: graphical config editor
Keybinds: compositor hotkey reference
otter-bar: status bar setup

Get Started

Desktop Shell

Core Apps

Productivity

Utilities

Configuration

Compositor autostart examples

Hyprland

Sway

Niri

Display manager

Session security flow

Protocol requirements

Next steps

​What runs at login

​Compositor autostart examples

​Hyprland

​Sway

​Niri

​Display manager

​Session security flow

​Protocol requirements

​Next steps

What runs at login

Compositor autostart examples

Hyprland

Sway

Niri

Display manager

Session security flow

Protocol requirements

Next steps