Choose a shell

Choose a complete shell or combine a bar, launcher and notification daemon. Bingux is a separate project and one example of a shell built on Gnoblin. It is optional.

Waybar, Fuzzel and Mako

Install Waybar, Fuzzel and Mako with your distribution's package manager.

Add this to ~/.config/gnoblin/init.lua:

gnoblin.configure {
    autostart = {
        bar = {command = {"waybar"}},
        notifications = {command = {"mako"}},
    },
    shortcuts = {
        launcher = {binding = "<Super>d", command = {"fuzzel"}},
    },
}

Configure Waybar's clock, tray and system modules as usual. Its Sway and Hyprland modules need those compositors' own interfaces and do not work in Gnoblin. Run one notification daemon; leave Gnoblin's native notifications disabled when using Mako.

Configure each tool in its own files. Gnoblin's autostart and shortcuts only control how you launch it.

Firefox is an ordinary client window; Waybar is a separate desktop client.

An app running with Waybar and Mako as separate clients.

Quickshell

Quickshell can host custom layer-shell surfaces. This small PanelWindow example runs beside Firefox:

import Quickshell
import QtQuick

PanelWindow {
    anchors { top: true; left: true; right: true }
    implicitHeight: 42
    Text {
        anchors.centerIn: parent
        text: Qt.formatDateTime(new Date(), "ddd, dd MMM  ·  HH:mm")
    }
}

The panel is a separate Quickshell process using Gnoblin's layer-shell support.

Bingux

Bingux is an integrated desktop with a bar, dock, search and notifications. See Bingux to install it.

What Gnoblin provides

Gnoblin provides window management, locking, desktop services, and a small recovery panel for shell setup.

Native notifications and the keyboard-layout popup are optional. See session settings.

Gnoblin paints a solid black background behind desktop surfaces so areas uncovered while windows move are repainted. This is not a wallpaper client. Wallpaper layer surfaces sit above the black background; use an existing client such as swaybg or the wallpaper client your shell already manages. See wallpapers.

If the shell does not appear

After startup, Gnoblin waits briefly for shell activity. A mapped top or overlay layer surface counts as shell activity; a bottom-layer wallpaper does not.

If none appears while the session is unlocked, the recovery panel offers:

• Open the configuration path reported by gnoblinctl config path.
• Launch a terminal, if one is installed.
• Read this shell setup guide.

If no configuration exists, the panel creates the default Lua configuration at that path. It does not replace an existing configuration.

Press Escape or choose Dismiss to hide the panel. It returns if shell readiness changes and the shell later disappears. The panel stays hidden while the session lock state is locked or unavailable.

If the panel does not appear, switch to another session or a text console and inspect the shell's service and logs.

For Bingux helper services, inspect the optional target:

systemctl --user status bingux.target
journalctl --user -b -u bingux-searchd.service -u bingux-statusd.service

See troubleshooting. To write your own shell, start with the compositor bridge.