A focused, modern desktop shell for Wayland.
Warning
Coconut is under active development and is not yet intended for daily use or distribution packaging.
Coconut puts common desktop actions within immediate reach: launch an application, move between running windows, control media, or adjust your system without losing focus. Its top statusbar and centered dockbar are designed to stay calm, responsive, and consistent.
- A configurable statusbar and dockbar, with widgets usable in either or both
- Island groups for visually separated widget sections
- A centered running-app dockbar with active-window feedback
- Application browsing, category navigation, and search
- A reusable Pinned apps widget with contextual
pinning and
.desktopfile drag and drop - Now-playing information with playback controls
- Clock and weather widgets
- A permission-controlled clipboard history service and optional history widget
- A control center for network, brightness, volume, Bluetooth, battery, and power profiles
- Floating volume and brightness indicators with configurable placement
- D-Bus desktop notifications with icons, actions, replacement and expiration
- Dedicated panels for the same system controls when you need more detail
- Native desktop integrations for Blair and KDE Wayland, plus Windows 10
Run the desktop and its local portal services without installing:
./scripts/dev.sh --build # Build into .build/ without UPX, then start Blair and Coconut.
./scripts/dev.sh # Use the existing staged binaries.The development session uses its own D-Bus bus and XDG directories. See the shell development guide for dependencies, Blair selection, logs and running additional apps in that session.
Use make dev, make build, or make test as shortcuts to the
repository scripts.
| Command | Purpose |
|---|---|
coconut |
Start the shell. |
coconut settings |
Open Coconut Settings. |
coconut bg |
Start the standalone background renderer. |
coconut-settings |
Open Coconut Settings directly. |
coconut-bg |
Render the desktop background directly. |
coconut terminal |
Start the terminal emulator. |
cedit [FILE ...] |
Open CEdit, the text, code, Markdown and byte editor. |
ccalc [--scientific] |
Open Calculator with standard/scientific modes and unit conversions. |
cviewer [IMAGE ...] |
Open Image Viewer with zoom, pan, rotation, temporary color adjustments and metadata. |
coconut-screenshots |
Take a screenshot and annotate it: drag to select, draw, blur, erase, then copy or save. --screen captures headlessly, --save-as asks where to save. |
coconut-permission-portal --service |
Run the permission service that stores per-application decisions and shows consent prompts. |
coconut-clipboard |
Run the session clipboard history service and its permission-controlled D-Bus API. |
cterm --settings |
Open Terminal Settings. |
coconut files |
Start the file manager. |
cfiles --settings |
Open File Explorer settings. |
cfiles --portal |
Run the FileChooser portal backend. |
coconut monitor |
Start the system monitor. |
coconut media-player |
Start the media player. |
cplayer --settings |
Open Media Player settings. |
coconut-greeter |
Start the Alphin login screen. |
coconut-greeter --preview |
Preview the login screen with sample accounts, without Alphin or Blair. |
coconut-greeter --preview-multiple |
Preview the account switcher and session dropdown. |
coconut now contains only the shell and transparent desktop-icon layer.
coconut-bg renders the desktop background as an independent session daemon;
the installed session profile launches both automatically — startcoconut
(the greeter-facing bootstrapper, which starts the compositor selected at
install time) hands off to coconut-session, which spawns coconut-bg, coconut-clipboard and
then the shell. Future session components get added there, not to the shell.
When running pieces by hand instead of through the session, start
coconut-bg alongside coconut yourself. It renders one bottom
layer surface per output, follows output size/scale changes, and stores its
independent configuration in ~/.config/coconut/bg.toml (or the equivalent
XDG configuration directory). Coconut Settings updates it live. Image mode
supports Full (aspect-preserving fill), Centered, Stretched, and
Mosaic placement. The background can also be a solid color, a two-color
linear gradient, or a built-in GPU shader animated through frame callbacks.
Each shader can be tuned independently for animation speed, target frame rate
(1-60 fps) and palette colors under [shaders.<name>]. When GPU rendering is
unavailable, shader mode falls back to the solid color.
Clipboard history is configured in Settings → Privacy → Clipboard. Enable its optional icon in Settings → Desktop → Islands. History stays in memory, with configurable size and expiration, and supports text on compositors with wlr-data-control, including Blair. See the service/API guide for permissions and configuration, and the widget guide.
Open Settings → Desktop → Notifications & popups to set the screen edge,
alignment, edge offset and duration separately for application notifications
and volume/brightness indicators. Coconut also shows its own notifications
when Wi-Fi or Bluetooth connects, disconnects, or is turned on/off. These use
the notification preferences directly and work without the D-Bus notification
service. Changes apply immediately. The same options
are stored in [notifications] and [status_updates] in shell.toml:
enabled, edge (top/bottom), align (left/center/right), offset
(in logical pixels) and duration_ms.
On Linux, Coconut provides org.freedesktop.Notifications on the session bus
when no other notification service owns that name. Test it with
notify-send -i dialog-information "Coconut" "Notifications are ready".
Application timeouts take precedence over the configured default; critical
notifications stay visible until dismissed unless the application sets a timeout.
Coconut desktop themes share resolved colors, typography and geometry across the shell, CreamUI, GTK and Qt. Packages can use automatic adapters or native overrides/templates. See THEMES.md for package authoring, dynamic variants/accents, session integration and compatibility details.
On Linux, Coconut integrates with Blair through its
org.blair.Compositor1 D-Bus API for window management and layer-shell
surfaces. KDE Wayland services are supported where available.
On Windows 10, Coconut uses native APIs and PowerShell for window discovery, application launching, media sessions, volume, power, display brightness, network, and Bluetooth. Unavailable hardware features fall back gracefully.
When Weather is enabled, Coconut resolves the configured location on first use, stores its coordinates in the user profile, and retrieves forecasts directly from MET Norway. Disabling the widget prevents new weather requests.
See the development documentation:
- Contributing: commit conventions, change boundaries, and contribution checks.
- Shell and session development: checkout layout, native dependencies, build commands, greeter previews, and troubleshooting.
- Application development: architecture, CreamUI components, design, interaction patterns, performance, and validation.
- Code style: source quality and comment rules.
Run ./scripts/setup.sh --dry-run to inspect native dependencies, then
./scripts/setup.sh to install them.
For a local development session:
cargo run -p coconut-background &
cargo run -p coconut-shellLaunch the settings application separately with:
cargo run -p coconut-settings