Cagebreak - ArchWiki

Jump to content

# Cagebreak

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 a 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 the configuration man page 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. Install `cagebreak` as per #Installation. You should use cagebreak-binAUR unless you have reasons to do otherwise.
2. Copy the example configuration from Github to `$XDG_CONFIG_PATH/cagebreak/config`. Documentation is provided in the configuration man page.
3. Install `xterm` or replace `xterm` with your preferred terminal emulator in the configuration file.
4. Run the following command or add it to `~/.bash_profile` to run cagebreak on login (see #Keyboard layout for explanation):
   - `XKB_DEFAULT_LAYOUT=us cagebreak`
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-<number>` to switch to the workspace `<number>`. For a full list of available keybindings, read the configuration file and the documentation.
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 readme 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 the man page 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

1. github
2. github wiki
3. pkgbuild on github

Category:

- Wayland compositors