cage

Run an application

$ cage [application]

$ cage -- [application] [arguments]

$ cage -d [application]

$ cage -s [application]

$ cage -h

cage [options] [--] [command [args...]]

-h, --help
    Display help message and exit

--version
    Print version information and exit

-c, --config FILE
    Load configuration from FILE (default: ~/.config/cage/cage.conf)

-d, --debug
    Enable verbose debug logging

-s, --single-buffer
    Disable double-buffering (use single-buffer mode)

--backend BACKEND
    Select backend: drm, headless, or wayland

-r, --renderer RENDERER
    Select renderer: gles2 or vulkan

--exit-on-last-app
    Exit compositor when last app terminates

--force-exit
    Allow exit IPC command even if apps are running

--ipc-socket PATH
    Path to control socket for IPC commands

Cage is a minimal Wayland compositor designed for kiosk and embedded applications. Built on the wlroots library, it provides a fullscreen environment for a single Wayland-compatible application, ignoring input outside that app. Ideal for digital signage, information displays, or locked-down systems, Cage supports hardware-accelerated rendering via DRM or headless backends.

Unlike full desktop compositors like Sway or Weston, Cage lacks window management, multiple desktops, or input configuration. It focuses on simplicity and low overhead, automatically relaunching the configured app on crash or exit (unless disabled). Users configure it via ~/.config/cage/cage.conf, specifying the app to run, scaling, and IPC sockets.

Cage integrates with standard Wayland tools like wayland-info and supports protocols for input, output, and security contexts. It's lightweight, with no dependencies beyond wlroots and Wayland libraries, making it suitable for resource-constrained devices.

Requires wlroots-compatible GPU drivers (e.g., Mesa); DRM backend needs seat0 access. No multi-monitor support by default. Runs fullscreen only; test apps with weston first. Nested Wayland may need WLR_NO_HARDWARE_CURSORS=1.

Edit ~/.config/cage/cage.conf for app command (e.g., exec foot), scaling, font, and IPC settings. Supports bindir for relaunching crashed apps.

Use Ctrl+Alt+F12 (default) or Super+Q; run echo 'exit' | socat - /run/user/$UID/cage.sock for IPC; or killall cage.

Helper command to exit Cage: cagebreak [-h | --version] . Binds to configured exit keys.

Developed by Daniel Martí (emersion) starting 2019 as part of wlroots ecosystem. First release 0.1.0 in 2020; now at v0.2.x. Focuses on kiosk use cases, with contributions for Vulkan renderer and headless backend. Maintained on GitHub with active wlroots integration.

cagebreak(1), wlroots(7), wayland(7), sway(1), weston(1)