About cage-kiosk/cage
Cage is a Wayland kiosk compositor designed to run a single, maximized application in fullscreen mode. Built on the wlroots library, it uses the Meson build system and supports optional XWayland for X11 applications. Cage can run inside an existing X11 or Wayland session (as a nested window) or directly on a TTY using the KMS/DRM backend. It is configured via environment variables and run options, with a debug mode that allows quitting via Alt+Esc. Released under the MIT license, Cage is ideal for digital signage, interactive kiosks, and single-purpose displays.
Key Features
Runs a single, maximized Wayland application in fullscreen kiosk mode
Built on the wlroots library with dependencies on wayland, wlroots, and xkbcommon
Optional XWayland support for running X11 applications
Runs inside an existing X11/Wayland session (nested) or directly on a TTY via KMS/DRM backend
Customizable via environment variables and run options
Debug mode with Alt+Esc to quit (default debug build)
Pros & Cons
Pros
- Lightweight and minimalistic, focused on a single task
- Open source under the permissive MIT license
- Based on mature and actively maintained wlroots library
- Supports XWayland for compatibility with legacy X11 applications
- Easy to build with Meson and minimal dependencies
Cons
- Limited to one maximized application (by design, not a general compositor)
- No window management or multi-window support
- Requires technical knowledge to build, configure, and deploy
- Only runs applications that support Wayland natively (XWayland optional)
Best For
Digital signage displaying a single web page or media playerInteractive kiosks for information or ticketingSingle-purpose displays in museums, retail, or public spacesEmbedded systems requiring a dedicated fullscreen application
FAQ
What is Cage?
Cage is a Wayland kiosk compositor that runs a single, maximized application in fullscreen mode.
How do I build Cage?
Cage uses the Meson build system. Run 'meson setup build' then 'meson compile -C build'. Dependencies include wayland, wlroots, and xkbcommon. Optionally install scdoc for manual pages.
How do I quit Cage?
In debug mode (default build), press Alt+Esc to quit. For release builds, the application must handle exit.
Does Cage support X11 applications?
Yes, optionally. Cage includes compile-time support for XWayland, but you must have XWayland installed and wlroots compiled with XWayland support.
How do I run Cage?
Run './build/cage APPLICATION'. If run inside an existing X11/Wayland session, it opens in a virtual output window. If run at a TTY, it uses the KMS/DRM backend.