This is the monorepository for the boring Wayland compositor. As the name implies, it is boring by default. However, the hacker in you will probably love it.
Warning
This is an experiment in developing a LuaJIT-based Wayland compositor. It isn't ready for serious desktop usage. I'm not currently working on it (as of June 28, 2026) and there's a lot of clean-up that must be done before feature development is continued.
boring is a minimalist, non-monolithic Wayland compositor built on wlroots that is designed to be hackable and extensible, reminiscent of dwm and dwl. Functionality is provided through plugins; we give you the tools and leave you to play.
A set of default plugins are included that provides basic window management and Wayland functionality for those that don't want to spend too much time writing their own:
animations: Windows fade in and out as they open and closeborders: Draw borders around windowsidle: Lock and turn the screens off after a while without inputipc: Run Lua in the running compositor:./boring.lua -e 'return #boring.windows()', or./boring.lua -ifor a REPLlauncher: A search field for applications, windows and arithmetic (Super+Space in the default config)layout-master: Master and stack layoutlayout-stacking: Traditional stacking layoutlayout-tiling: Sway-inspired n-ary tiling layoutlayout-kiosk: Runs a single, maximized windownotifications: Notification cards stacked in a corner, from applications over D-Bus (through the installed sd-bus or libdbus), with actions, do not disturb and historyrules: Window rules as Lua functions returning properties (floating, size, workspace, …)workspaces: Several workspaces per output, shown to panels overext-workspacescreenshot: Screenshots of an area, a window or an output, with blur, pen, box and arrow tools; saved as PNG and copied, with no external toolswallpaper: Wallpaper pluginxwayland: XWayland integration
The default configuration automatically mounts animations, borders, ipc, launcher, layout-stacking, notifications, screenshot, wallpaper, and xwayland. The documentation for each plugin can be found in their respective files.
The compositor is entirely written in LuaJIT. For this reason, using and developing the compositor is the same process, as you'll be running the compositor from source.
To get started with boring, you need the following dependencies installed:
- LuaJIT
- The most recent version of
wlroots, which at the time of writing is 0.20, pluslibinputandlibxkbcommon wlr-protocolsandwayland-protocolsinstalled
No compiler or -devel headers are needed: the FFI declarations are generated ahead of time and committed under shared/ffi.
Some additional dependencies may be needed depending on the plugins you choose to use. The default plugins depend on xwayland, which requires xorg-server and libxcb, as well as libvips for text, icons, images and screenshots. Notifications use the D-Bus client library that's installed (libsystemd, libelogind, libbasu or libdbus) and turn themselves off without one.
To try the compositor inside your current Wayland session, run it nested with wlroots' Wayland backend; it opens as a regular window on your host compositor:
WLR_BACKENDS=wayland ./boring.lua --config=configs/nested-wayland.luaconfigs/nested-wayland.lua avoids host-reserved Super-key shortcuts,
launches xeyes once on startup, and binds:
Alt+ReturnorCtrl+Alt+Return: launchxeyesAlt+t: launchfootAlt+q: close the focused windowAlt+Shift+qorCtrl+Alt+q: exit the compositor
On macOS, use the development VM instead; see dev/README.md.
Saving the configuration file reloads it (plugins are remounted, keyboards reconfigured); a config with errors is refused and the running one stays. Pass --watch=false to turn that off.
To download the compositor, clone the repository, then run boring.lua from it:
git clone https://github.com/loukamb/boring.git
cd boring
./boring.luaThe dependencies for development are the same as for usage. If you can run the compositor, you're good to go.
/compositor: The compositor: one module per responsibility, sharing aserverrecord/plugins: Default plugins/clients: Tiny programs providing basic desktop functionality/shared: Code shared by the programs: FFI bindings (ffi), wlroots helpers (wl), utilities/tools: Development tools (FFI binding generator and checks)/dev: Development VM for macOS/website: Website for the project
See ARCHITECTURE.md for the design and coding principles.
The C declarations LuaJIT needs live in shared/ffi and are generated by tools/ffi_gen.lua from the installed headers. Regenerate them after bumping wlroots (or adding a header or protocol to the generator), then check the struct layouts against the C compiler and review the diff:
luajit tools/ffi_gen.lua && luajit tools/ffi_check.lua # or: scripts/vm ffi-genGeneration needs gcc, pkg-config and the -devel packages; running boring doesn't.
Tests are split by how much compositor machinery they need:
tests/unit: pure Lua and parser/config tests.tests/service: wlroots-adjacent service and plugin tests using fake objects or direct helper APIs.tests/integration: headless compositor scenarios driven throughtests/harness.
Run the full suite locally with:
luajit tests/run.lua --suite allCI uses TAP output:
luajit tests/run.lua --suite unit --format tap
luajit tests/run.lua --suite service --format tap
luajit tests/run.lua --suite integration --format tapLifecycle hygiene check:
rg "listener\.connect|setmetatable" compositor pluginsThis should only match compositor/config and compositor/plugin.lua (the sandbox environments for config and plugins). Listeners in compositor modules and plugins go through a scope (scope:listen), so they're disconnected when the object they belong to goes away.
To write a plugin, put a Lua file in the ~/.config/boring/plugins directory that returns a table with a name field and a mount function. You can also create a folder and move your plugin's entrypoint to $DIR/init.lua if you have to ship multiple files, or mount a file by path (plugin("./my-plugin.lua")). To enable your plugin, add it to your configuration file:
-- This will load and mount the plugin.
-- :mount() returns the plugin object.
local my_plugin = plugin("my-plugin"):mount()The table passed to :mount is given to the plugin's mount function, which allows you to pass configuration to the plugin:
-- config.lua
local my_plugin = plugin("my-plugin"):mount({ value = "hello" })
-- plugins/my-plugin.lua
local plugin = { name = "my-plugin" }
function plugin:mount(config, ctx)
print(config.value)
-- This value will be returned to the :mount() invoker.
return { a = 1 }
end
return pluginPlugins and configuration share the same globals, so anything that's possible in configuration is possible in plugins. Both talk to the compositor through the boring global (compositor/api.lua). mount also gets a ctx (compositor/plugin.lua):
ctx.scopeundoes everything registered through it when the plugin is unmounted, so most plugins need nounmountfunction (it's optional).ctx.stateis a table that survives config reloads, for state that shouldn't be lost when the plugin is remounted.
function plugin:mount(config, ctx)
ctx.scope:subscribe(boring.events, "window:map", function(window)
print("new window", window:title(), window:app_id())
window:set_position(100, 100)
end)
ctx.scope:defer(function() print("unmounted") end)
endWhen the config is saved, plugins it mounts with the same config (and an unchanged file) stay mounted; the others are remounted, and plugins it no longer mounts are unmounted.
Plugins don't require each other. Code shared between plugins goes in a library, require("@boring/library/<name>"), which is loaded once per compositor and kept across reloads. The included ones:
scene: the scene graph as Lua objects: trees, solid rects and images, with position, size, colour, opacity, snapshots and clicksspaces: windows grouped into spaces per output and arranged by layout pluginsworkspaces: several spaces per output, published overext-workspacefullscreen: fill an output and put the window back afterwardstext: text drawn into the scene, with ellipsis and wrappinganimate: animated values; borders, stacking and wallpaper colours take them anywhere they take a colourdesktop: desktop entries (localised, filtered, field codes) and icon theme lookupcaptureandpixels: the screen read back as pixels, and drawing on them (blur, lines, boxes, arrows)ui: widgets the compositor draws itself (text, images, boxes with rounded corners, rows, columns, buttons, inputs, lists), themed with plain tables;boring.grab_keyboardandboring.grab_pointergive them input
Events: window:map, window:unmap, window:focus, window:blur, window:commit, window:title, window:fullscreen, window:maximize, window:urgent, output:add, output:change, output:usable, output:remove, ready, shutdown. Windows have position, set_position, geometry, bounds, size, set_size, raise, close, title, app_id, set_enabled, visible, set_fullscreen, set_maximized, set_urgent and a data table for plugin state (compositor/window.lua).
Core doesn't manage windows: a new window opens at the origin of the output under the cursor, and what clients ask for arrives as events (window:request_move, window:request_resize, window:request_fullscreen, window:request_maximize, window:request_minimize) for plugins to answer. boring.begin_move, boring.begin_resize and boring.grab_pointer are the tools for it. The layout plugins share library/spaces, which documents how to write one. Plugins draw through library/scene. Libraries that need more have boring.wl (wlroots itself) and boring.server (the compositor's objects); plugins stay off them.
For examples on how to write plugins, see the default plugins.
BSD Zero Clause License
Copyright (c) 2026 Louka Ménard Blondin <hello@louka.sh>
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.