Jump to content
From ArchWiki

Related articles

- Wayland#Compositors
- Window manager

Cagebreak is a tiling compositor for Wayland, based on cage and inspired by ratpoison, which is easily controlled through the keyboard and a UNIX domain socket.

## Installation

Install cagebreakAUR or cagebreak-binAUR. Alternatively, download the release tarball or clone the repository.

### Optional dependencies

- wl-clipboard for copy/paste capabilities
- xorg-xwayland for allowing Xorg applications to run under cagebreak

## Configuration

The general configuration for cagebreak is located in `$XDG_CONFIG_PATH/cagebreak/config`. This defaults to `~/.config/cagebreak/config`.

Read cagebreak-config(5) for detailed information. Note that you can also add configuration by using #Interaction through socket.

An example configuration file may be found on GitHub.

## Usage

Start cagebreak like any other binary.

### Getting started

The following is an example of how to install and use cagebreak with the configuration file provided on GitHub.

1. Follow #Installation.
2. Copy the example configuration from GitHub to `$XDG_CONFIG_PATH/cagebreak/config`. Documentation is provided in cagebreak-config(5).
3. Install xterm or replace `xterm` with your preferred terminal emulator in the configuration file.
4. Run `XKB_DEFAULT_LAYOUT=us cagebreak` or autostart it to run cagebreak on login (see #Keyboard layout for details).
5. Cagebreak should start up and display the terminal emulator you specified above. Press `C-t` `t` to open a new terminal or `C-t` `S` to split the screen. You can also use `Alt-n` to switch to the workspace `n`. For a full list of available keybindings, read the configuration file and cagebread-config(5).
6. If you wish, you may also interact with cagebreak using the UNIX domain socket. See #Interaction through socket for further information.
7. Also, please file any bugs you may find:
   - GitHub issue tracker or via email as per the SECURITY.md for cagebreak
   - AUR comments for the cagebreak-binAUR and cagebreakAUR PKGBUILDs

### Keyboard layout

Set the environment variable `XKB_DEFAULT_LAYOUT` to the desired keyboard layout. See cagebreak(1) § ENVIRONMENT for further information.

### Interaction through socket

On startup, cagebreak opens a UNIX domain socket through which interaction with the compositor is possible at run-time. The path to this socket is stored in the `CAGEBREAK_SOCKET` environment variable. For example, openbsd-netcat may be invoked with:

    $ nc -U $CAGEBREAK_SOCKET

to send cagebreak any configuration while it is running. The syntax is identical to the syntax of the configuration file.

## See also

- GitHub
- PKGBUILD on GitHub

Category:

- Wayland compositors