A small, modern Wayland compositor that leaves the desktop yours.
Warning
Blair is under active development and is not yet intended for production or daily use.
Blair handles windows, workspaces, input, outputs, and session plumbing while leaving the rest to you. Choose your own bar, wallpaper, launcher, notifications, and shell. Coconut is an optional companion shell, never a requirement.
- Native Wayland compositor with nested Winit and direct DRM/KMS backends
- Damage-tracked rendering, hardware cursors, and DRM overlay planes
- Per-output workspaces and configurable tiling or floating layouts
- Layered TOML configuration with safe hot reload
- Configurable outputs, input, focus, decorations, autostart, and animations
- D-Bus APIs for shells, panels, launchers, and external tools
- Modern Wayland protocols including layer-shell, dmabuf, screencopy, and data control
Create ~/.config/blair/config.toml:
[[autostart]]
command = "waybar"
restart = true
[[autostart]]
command = "swaybg -i ~/Pictures/wallpaper.png"
[[autostart]]
command = "mako"
[[bindings]]
keys = ["SUPER", "RETURN"]
exec = "foot"
[[bindings]]
keys = ["SUPER", "Q"]
action = "close"No shell or main client is required. Use blair --run foot to start a one-off
application for the current session; repeat --run when needed.
Every setting is optional. Defaults provide click-to-focus, focused new windows, ten workspaces, automatic output selection, and animations.
[[bindings]]
keys = ["SUPER", "1"]
action = "workspace"
value = 1
[workspaces]
count = 10
dynamic = false
wrap = true
[window]
layout = "tiling" # floating | tiling
work_area_padding = 16
gap = 8
master_ratio = 0.55Workspaces are global identities, while each output displays a different one. Floating windows open centered; tiling assigns the first window a master column and stacks the rest beside it.
[[rules]]
app_id = "pavucontrol"
floating = true
size = [700, 500]
[decorations]
mode = "auto" # server | hybrid | client | auto | none
border_width = 2
corner_radius = 8
titlebar_height = 28mode = "hybrid" forces server-side decoration negotiation, but leaves the
client at its original size and draws only the configured window controls over
its top-right corner. It does not draw a titlebar, title text, icon, border, or
draggable server region.
Rules match app_id, title, or regex and can set layout, workspace, output,
size, position, opacity, stacking, and decorations.
[outputs."DP-1"]
enabled = true
mode = "2560x1440@165"
position = [0, 0]
scale = 1.0
vrr = true
[input.touchpad]
tap = true
natural_scroll = false
disable_while_typing = true
[animations]
enabled = trueWithout explicit output entries, Blair uses a safe automatic profile. Cursor
settings fall back to XCURSOR_THEME and XCURSOR_SIZE and are passed to
applications Blair starts.
general.output_mode = "auto" is the default. It selects the monitor's preferred
mode, or the highest resolution and refresh rate when the monitor does not mark
one. mode = "auto" on an output does the same. A saved WIDTHxHEIGHT@REFRESH
mode takes precedence. output_mode = "initial" with
general.initial_output_size = [1366, 768] requests that size instead. Physical
outputs advertise all their supported modes through Wayland and DisplayInfo
on D-Bus. ApplyDisplayMode previews a supported size and refresh rate for 15
seconds; ConfirmDisplayMode saves it in the user configuration, while
RevertDisplayMode or the timeout restores the previous mode. Nested outputs
report their host window size and do not offer physical mode changes. The DRM
backend currently activates one connector; these controls apply to that output.
DEVELOPMENT.md covers the required checkout layout, native dependencies for Arch, Debian/Ubuntu, Fedora/RHEL, and openSUSE, the distinction between libseat and seatd, testing, and local installation.
For a nested local session:
RUST_LOG=blair=debug,warn cargo run -p blair--profile user is the default. Later TOML layers override earlier ones:
built-in defaults
/etc/blair/config.toml
/etc/blair/conf.d/*.toml
~/.config/blair/config.toml
~/.config/blair/conf.d/*.toml
--profile <id> loads /etc/blair/profiles/<id>.toml over the built-in defaults
and does not read the user directory. Kiosk mode is general.kiosk in that
file. Settings changed at runtime are stored only for the user profile.
Blair validates every layer before applying it, so an invalid edit preserves the previous configuration. See the bundled example for the full schema.
| Area | Implementation |
|---|---|
| Compositor | Smithay, XDG shell/decoration, layer-shell, clipboard and DnD |
| Backends | Winit nested development; DRM/KMS, libinput, and libseat direct sessions |
| Rendering | GLES2, damage tracking, DRM planes, shader-based decorations |
| Integration | Transport-neutral CompositorApi, Transport, and EventChannel |
| Default transport | Optional D-Bus (integrations.dbus = true) |
Blair supports the core Wayland protocols plus xdg-shell, xdg-decoration,
layer-shell, linux-dmabuf, presentation-time, fractional-scale, screencopy,
data control, and KDE server decoration. Tools that use wlr-screencopy, such
as grim and wf-recorder, use the configured screen-capture permission policy.
The D-Bus service is org.blair.Compositor at /org/blair/Compositor, using
the org.blair.Compositor1 interface. It exposes window and workspace control,
outputs, settings, shortcuts, screenshots, and render statistics.
integrations.screencopy governs both wlr-screencopy requests and the
org.blair.Compositor1.Screenshot D-Bus method:
| Policy | Behavior |
|---|---|
ask (default) |
Ask Coconut's permission service; deny if unavailable. |
ask-safe |
Ask the service; allow if unavailable. |
allow |
Allow capture without a permission prompt. |
deny |
Reject requests without contacting the permission service. |
Install the current Coconut permission portal alongside Blair. The cancellable
native protocol uses BeginRequest, WaitRequest, and CancelRequest on
org.coconut.Permissions1. An older portal without those methods is treated as
unavailable. Install the updated portal before running the updated compositor.
The compositor identifies Wayland clients from their socket credentials and D-Bus callers from their bus credentials. Subjects are executable paths or Flatpak application IDs. The caller cannot supply a different application's identity to the screenshot method.
Authorization is asynchronous, with at most 64 outstanding requests. A prompt
for one application does not block requests for another or unrelated D-Bus
methods. Admission rejects overload under every policy that uses the service;
ask-safe does not bypass a full local authorization queue. Ordinary D-Bus
calls have a separate limit of 128 pending compositor replies.
Capture verdicts use a bounded completion table and the compositor's wakeup source, so a full general command queue cannot discard them. Transport shutdown resolves pending requests using their configured unavailable-service policy. Frame destruction and client disconnection cancel the corresponding request. The portal closes a shared prompt only after its final waiter is cancelled. D-Bus client disconnection cancels its pending screenshot consent as well.
Validation includes private D-Bus service tests and Wayland protocol tests:
cargo test --workspace
cargo clippy --workspace --all-targets --no-deps -- -D warnings
cargo fmt --all -- --checkThe capture lifecycle tests do not require a GPU. Tests marked as requiring EGL remain opt-in for native rendering validation.
If a session becomes unresponsive, switch to a TTY with Ctrl+Alt+F2 and run:
pkill -9 blairSession logs live in $XDG_STATE_HOME/blair/compositor.log or, by default,
~/.local/state/blair.
Blair is distributed under the Apache License 2.0.