Gnoblin
Docs

Build a floating desktop

Gnoblin supplies the compositor, window management and interfaces that desktop components can use. A shell supplies the visible controls. The shell can be one program or a collection of smaller clients; it is independent of Gnoblin. Bingux is one separate project built on these interfaces.

On this page
Piece Gnoblin provides Your desktop chooses
Windows Focus, move, resize, workspaces, rules and decorations Dock grouping, switcher order and menus
Input Keybindings and input-source control Launcher, search and popup design
Surfaces Layer-shell placement, exclusive zones and effects Bar, dock, wallpaper and overlays
Desktop services Portal routing, and optional native features Portal backend, notification daemon and other visible controls

Firefox in a Gnoblin session with the Bingux dock

Bingux is one separate shell example; Gnoblin provides the compositor and window management.

The configuration reference describes the Lua settings. The CLI is convenient for commands; the compositor bridge supplies subscriptions and shortcuts to a long-running shell. Wayland protocols serve native clients, and Lua event handlers react to compositor events.

Assemble a small desktop

Install a bar, launcher, notification daemon and terminal. This example uses Waybar, Fuzzel, Mako and Foot. They are independent applications; replace any of them with a component you prefer. Put this in a new ~/.config/gnoblin/init.lua:

Lua
gnoblin.configure {
    cursor = {theme = "default", size = 28},
    autostart = {
        bar = {command = {"waybar"}},
        notifications = {command = {"mako"}},
    },
    shortcuts = {
        launcher = {binding = "<Super>d", command = {"fuzzel"}},
        terminal = {binding = "<Super>Return", command = {"foot"}},
    },
}

Settings app open under Waybar

A settings app beneath Waybar.

The cursor uses your system's default theme. See the cursor guide to choose another installed theme.

Capture this example from the checkout with scripts/capture-doc-examples.sh waybar-settings. It uses a disposable config and profile; see the capture script for setup.

A shell or package that installs Lua files into /usr/share/gnoblin/conf.d/ needs nothing in the user's init.lua: Gnoblin loads those files before init.lua (see system drop-ins).

If your existing init.lua loads other files installed by a shell, keep those gnoblin.load(...) lines and put your additions after them. Use an imported shortcut's existing name when changing its command. Load order and merging explain why the order matters.

Log in to Gnoblin, then run gnoblinctl config path to confirm the active file. Run gnoblinctl config reload to apply edits; Gnoblin reports any configuration errors. See the autostart guide for launch timing and named entries.

Waybar's Sway and Hyprland modules expect those compositors' own IPC and do not gain that IPC merely by running under Gnoblin. Configure supported generic modules or write a module using window data.

Give each visible function an owner

Start one notification daemon from your shell or the session's autostart configuration. Configure window switchers and keyboard-layout popups in your shell. Gnoblin's input API selects the active input source; see input-source settings. Use shortcut guidance to resolve binding conflicts.

A dock can use the foreign toplevel protocols for basic window handles or the bridge for records, previews, activation and shortcut sessions. Keep window IDs only for the lifetime of their windows. Refresh snapshots after windows close or workspaces change. Bridge examples show clients in several languages.

Choose the right interface

Task Interface
Change a window from a script gnoblinctl window ...
Maintain a live switcher or dock Compositor bridge windows subscription
Place a bar or dock zwlr_layer_shell_v1
Capture output with a native client zwlr_screencopy_manager_v1, subject to its protocol gate
Apply per-app styling gnoblin.window_rule in Lua
React to a window or workspace event Lua callback registered with gnoblin.on
Supply an application titlebar Frame rule and optional renderer service

The desktop portal backend decides what each app may do. Disabling a Wayland protocol does not change what a portal backend allows for screen sharing or remote control; see portal routing.

Work on the desktop in a nested session

The devkit starts Gnoblin in a window. Use it to try a bar or rule before logging out.

For screenshots and demos, give it fresh home and XDG config, data, cache, state, and runtime directories. Launch only the applications that belong in the example. A normal devkit invocation keeps your real home directory; see the isolation notes.

For packaging or a final session check, use a real Gnoblin login. A devkit image proves what appeared in that nested run, not what is installed in a login session.

Continue from here

Edit this page on GitHub
Esc

Try