Pinnacle: a Smithay-based Wayland compositor with an AwesomeWM-style tag system

The pitch is AwesomeWM for Wayland, and the author says so

Pinnacle is a Wayland compositor built in Rust using Smithay, and the README says what it is trying to be: it's my attempt at creating something like AwesomeWM for Wayland.

That framing is more useful than a feature list because it names the exact workflow being ported. AwesomeWM is a tiling window manager organised around tags, where every window belongs to a tag and you switch between tags to switch between workspaces, with layouts assigned per tag. A user who has that mental model already knows what to expect from a tag system, and a user who does not will find the concept foreign in a good way.

The feature list is short enough to read in one pass: a tag system, dynamic tiling, customizable layouts, support for most wlr protocols, floating window support, Xwayland support, configurable in Lua or Rust.

Two of those carry more weight than their position in the list suggests. Dynamic tiling means the layout rearranges as windows open and close rather than requiring a manual re-tile, which is what distinguishes a modern tiling compositor from a static one. And configurable in Lua or Rust is unusual: most Wayland compositors expose one scripting language, and Pinnacle offers both, with the Lua path being the accessible one and the Rust path being the one that can reach deeper into the compositor.

The project is GPL-3.0 licensed, the primary language is Rust, the homepage is pinnacle-comp.github.io/pinnacle, and the last push was on 2026-06-27 with the v0.2.4 release tagged the same day, after v0.2.3 in February 2026 and v0.2.2 in January 2026.

Smithay does the graphics work, which is the point of the dependency

The dependency list in the workspace manifest shows what Pinnacle actually is: a layer of window management and configuration on top of a compositor library.

Smithay is pulled from git rather than from a registry, pinned to a specific revision of 599857c, with the default features turned off and features enabled selectively, including desktop and wayland_frontend. The remaining wayland stack in the manifest is wayland-backend at 0.3.12 and wayland-scanner at 0.31.8, which are the plumbing for talking to a Wayland server and for generating protocol bindings.

So Pinnacle does not implement a display server from nothing. The README's thanks section is explicit about the division of labour: thanks to Smithay for being a great compositor library and also allowing me not to deal with all the graphics stuff I still don't understand.

That is a candid statement and it maps exactly onto what the dependency tree shows. The graphics side, the output handling, the protocol plumbing and the input stack come from Smithay. What Pinnacle adds is the workspace model, the tiling engine, the layout system, the Lua and Rust configuration APIs and the keybinding and rules layer.

The rest of the workspace dependencies describe the shape of the rest of the system. clap with the derive and string features is the command line parser for the compositor binary. tracing and tracing-subscriber with env-filter and registry is the logging stack, with the env-filter feature implying you can select log levels by environment variable. tracy-client is there for the Tracy profiler. tokio with the multi-thread runtime, plus tokio-stream and futures, are the async runtime. bitflags for bitflag types, thiserror for error enums, anyhow with backtraces for application errors, walkdir for directory traversal and tempfile for temporary files.

The Rust edition is 2024 and the minimum rust-version is 1.88, so this is a codebase that expects a current toolchain.

Two API surfaces, and the Rust one reaches further

Pinnacle publishes two API references: a Lua one and a Rust one, at separate documentation sites. The distinction is not cosmetic, and the repository layout shows how it is built.

There is a pinnacle-api-defs directory at the workspace root, and separate api/rust, api/lua/build and api/lua directories. There is a snowcap directory containing its own snowcap-protocols, api/rust and snowcap-api-defs crates, and snowcap-derive. The presence of prost and tonic-build in the dependency list, along with tonic and tonic-reflection, tells you the API definitions are described as protobuf messages and the Rust side is generated from them.

So the architecture is: one set of API definitions, code generated into a Lua library and a Rust crate, and two clients of those definitions. That is why the Lua API can exist at all, because Lua cannot import Rust directly, so the interface has to be a wire protocol rather than a set of function calls.

The practical consequence for a user is that the two paths are not equally powerful. The Rust API is in-process, which means it can reach compositor internals directly. The Lua API crosses a process boundary over protobuf, which means every call has a serialisation cost and every capability has to be exposed deliberately through the definitions. That is a genuine constraint on what a Lua configuration can do, and it is the reason the Rust path exists rather than being a convenience.

The wiki directory at the repository root holds the documentation source, and the getting started introduction page is where the README sends anyone who wants to build or run the compositor. The API references live on their own sites and are separate from the wiki, which tells you the wiki is about operating Pinnacle and the references are about extending it.

The build uses just, LuaRocks and a protobuf install step

There is no single install command in the README, because the compositor has more than one kind of dependency. The justfile at the repository root is where the real workflow lives.

The justfile sets its shell to bash with the -c flag, computes the root directory, and derives the XDG data directory as the XDG_DATA_HOME environment variable falling back to $HOME/.local/share, followed by /pinnacle. The Lua version is pinned to 5.4.

The install target is a composition.

install: install-protos install-lua-lib install-snowcap

Three things happen. The protobuf definitions are installed, the Lua library is installed, and snowcap is installed. The protobuf step is described as only needed for the Lua API, which matches the architecture described above: the Lua side talks over protobuf, so it needs the definitions on disk.

install-protos:
    #!/usr/bin/env bash
    set -euxo pipefail
    proto_dir="{{xdg_data_dir}}/protobuf"
    rm -rf "${proto_dir}"
    mkdir -p "{{xdg_data_dir}}"
    cp -r "{{rootdir}}/api/protobuf" "${proto_dir}"

The script removes the destination directory, recreates the parent, and copies the api/protobuf tree from the repository into it under the XDG data directory.

The Lua library step requires Luarocks, and the justfile has a fair amount of care around how Luarocks is found. It shells out to which luarocks and treats a missing binary as an empty string rather than an error, and it calls luarocks path with either --full or without it depending on whether the installed version supports that flag, then appends the existing LUA_PATH so a system-wide path is not clobbered. The same pattern is repeated for LUA_CPATH with --lr-cpath. The comment in the file calls it a dirty trick until just's which() is stabilized.

So building Pinnacle is a chain of toolchains: Rust for the compositor, Lua and Luarocks for the Lua library, and protobuf definitions for the Lua API to talk over. There is a flake.nix and a flake.lock for Nix users, a nix/ directory, a Cargo.toml, and a justfile with a list target that prints the available recipes.

Xwayland and wlr protocols decide what you can actually run

Support for most wlr protocols and Xwayland support are the two features that determine whether Pinnacle is usable as a daily driver rather than as a demonstration.

Xwayland support means the classic X11 applications keep working. Without it, a compositor is limited to native Wayland clients, and a large part of the desktop software ecosystem is native Wayland but not all of it. The Xwayland integration is what lets a browser with an X11 build, an older Electron app or a proprietary tool run at all.

The wlr protocol support covers the extensions that wlroots compositors implement and that applications use for things the core Wayland protocol does not include: layer shell for panels and backgrounds, the foreign protocol for desktop windows, fractional scale, output management, screencopy for screenshots and screen recording, xdg activation and others. The wording is most wlr protocols rather than all, which is the honest way to say it, and it means the set of applications Pinnacle handles well is defined by that coverage.

The consequence for an adopter is that protocol coverage is a compatibility list, not a yes or no. An application that needs a specific wlr extension will work if that extension is implemented and will fail in a way that looks like a bug if it is not, and the README does not enumerate which protocols are supported. The wiki and the issue tracker are where that list is.

Xwayland also carries a cost that the feature list does not mention: Xwayland is a separate process running the X11 server, and applications inside it are not subject to Wayland's isolation model in the same way. A compositor that supports it is choosing compatibility over strictness, and the security posture of the session depends on how that is configured.

Where Pinnacle is the wrong tool

The first wrong-tool case is a person who wants a stable everyday desktop. The version line is 0.2.x, which by Rust and Cargo convention means the API is not stable and the release is not a guarantee. The README is unusually thin, and it is thin by choice: it points at the wiki for getting started, building and running, and there is no stability statement, no support policy and no list of known-good configurations. The roadmap lives in issue 403, which is a reasonable convention for a single-maintainer project and also means the plan is a discussion thread rather than a document.

The second case is someone who wants a Lua configuration to do everything. The Lua API is reachable only over protobuf from a separate process, so the operations available to it are whatever the API definitions expose. If you are coming from AwesomeWM expecting to reach into arbitrary C functions, the ceiling is lower, and the ceiling is set by the definitions in pinnacle-api-defs rather than by anything you write in your config.

The third case is a user who does not want to touch a Nix or Rust toolchain. Building this involves Cargo, Lua 5.4, Luarocks, protobuf definitions and a justfile, and the Lua library step alone needs Luarocks on the path with a version of just that handles the path flag difference. That is a real barrier for someone who expected a package to install.

The fourth case is a display server rather than a window manager. Pinnacle is a compositor in the Wayland sense, but the feature set described is a window management model: tags, tiling, layouts, floating windows. Anything expecting the full scope of a modern Wayland compositor's input handling, output configuration, display management and power features is outside what the README describes.

What you get in exchange is a compositor you can plausibly read. The special thanks note credits Niri for rendering and protocol inspiration and session stuff and the test fixture, and there is a wlcs_pinnacle directory in the workspace alongside a tests/ directory, which is a compositional test harness rather than a hand-rolled set of scripts. The projects it leans on are named and credited rather than hidden, which for a compositor means you can read the layers you did not write.

Editorial conclusion

Pinnacle suits someone who liked AwesomeWM's tag and layout model and wants it on Wayland with a Lua configuration they can write in an afternoon, since the compositor is small enough to read and the Lua reference is published. It does not suit someone who wants a mature, everyday driver for their laptop, because the release line is still 0.2.x and the README points at a wiki rather than documenting stability. Before adopting, read the getting started introduction in the wiki, check the roadmap issue 403 for what is still planned, and decide between the Lua and Rust configuration paths early, because they expose different amounts of the compositor.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. pinnacle-comp/pinnacle on GitHub
3. Project website
4. README
5. Releases