Features

This chapter provides a high-level overview of what Jay can do. Each feature links to the chapter where it is covered in detail.

Configuration

Jay can be configured via:

• a declarative TOML file, or
• a shared library that gets injected into the compositor for programmatic control.

Most users will use the TOML file. The configuration supports composable actions, input modes for vim-style modal keybindings, and powerful match rules. See Configuration Overview for details on getting started and how the config file works.

i3 Look and Feel

Jay provides an i3-inspired tiling layout with manual tiling, horizontal/vertical splits, fullscreen, and floating windows. Its appearance is based on the default i3 look and feel.

Colors, sizes, and fonts can all be customized. See Theme & Appearance for details, and Tiling and Floating Windows for how window management works.

Stability

Jay has been stable for a long time. Crashes and incorrect behavior in released versions are rare.

Jay also aims to be forward and backward compatible for existing setups, allowing you to upgrade or downgrade the compositor without having to adjust your configuration.

There is a small but growing integration test suite that is used to ensure this.

Command-Line Interface

Jay has a comprehensive CLI that can be used to inspect and configure the compositor at runtime. All query commands support --json for machine-readable output:

~$ jay
A wayland compositor

Usage: jay [OPTIONS] <COMMAND>

Commands:
  run                  Run the compositor
  config               Create/modify the toml config
  generate-completion  Generate shell completion scripts for jay
  log                  Open the log file
  set-log-level        Sets the log level
  quit                 Stop the compositor
  unlock               Unlocks the compositor
  screenshot           Take a screenshot
  idle                 Inspect/modify the idle (screensaver) settings
  run-privileged       Run a privileged program
  run-tagged           Run a program with a connection tag
  seat-test            Tests the events produced by a seat
  portal               Run the desktop portal
  randr                Inspect/modify graphics card and connector settings
  input                Inspect/modify input settings
  xwayland             Inspect/modify xwayland settings
  color-management     Inspect/modify the color-management settings
  clients              Inspect/manipulate the connected clients
  tree                 Inspect the surface tree
  control-center       Opens the control center
  version              Prints the Jay version and exits
  pid                  Prints the Jay PID and exits
  help                 Print this message or the help of the given subcommand(s)

Options:
      --log-level <LOG_LEVEL>  The log level [default: info] [possible values: trace, debug, info, warn, error, off]
      --json                   Output data as JSONL
      --all-json-fields        Print all fields in JSON output
  -h, --help                   Print help (see more with '--help')

See the full Command-Line Interface reference for details.

Control Center

Jay includes a built-in GUI control center (opened with alt-c) for managing outputs, input devices, GPUs, idle settings, color management, and more – without editing the config file. See Control Center.

Multi-Monitor Support

Jay can be used with multiple monitors with hot-plug and hot-unplug support. When a monitor is unplugged, all of its workspaces are automatically moved to one of the remaining monitors. When the monitor is plugged in again, these workspaces are restored.

See Outputs (Monitors) for configuration options.

Multi-GPU Support

Jay can be used with multiple GPUs and monitors connected to different GPUs. One GPU is always used for rendering the desktop. You can change this GPU at runtime.

See GPUs for details.

Screen Sharing

Jay supports screen sharing via xdg-desktop-portal. Three capture modes are available:

• Window capture – share a single window.
• Output capture – share an entire monitor.
• Workspace capture – like output capture, but only one workspace is shown.

See Screen Sharing for setup instructions.

Screen Locking

Jay can automatically lock your screen and disable outputs after inactivity. See Idle & Screen Locking for configuration options.

Notifications

Jay supports the zwlr_layer_shell_v1 protocol used by notification daemons such as mako, which is launched automatically by the default configuration.

Fractional Scaling

Jay supports per-monitor fractional scaling. Scale factors can be set per output in the config file or at runtime via the control center and CLI.

See Outputs (Monitors) for details.

OpenGL and Vulkan

Jay can use either OpenGL or Vulkan for rendering. Vulkan offers better performance and memory usage but OpenGL is still provided for older hardware.

You can change the rendering API at runtime without restarting the compositor.

See GPUs for details.

Explicit Sync

Jay supports explicit sync for compatibility with Nvidia hardware. This requires Linux 6.7 or later.

Xwayland

Jay supports running X11 applications seamlessly through Xwayland. See Xwayland for configuration options.

Clipboard Managers

Jay supports clipboard managers via the zwlr_data_control_manager_v1 and ext_data_control_manager_v1 protocols.

Privilege Separation

Jay splits protocols into unprivileged and privileged protocols. By default, applications only have access to unprivileged protocols. This means that tools like screen lockers, status bars, and clipboard managers need to be explicitly granted access.

Jay provides several ways to grant privileges, from giving a program full access to all privileged protocols down to granting individual capabilities to specific tagged processes. See Granting Privileges for a detailed guide and the Protocol Support section below for the full list of protocols and their privilege requirements.

Push to Talk

Jay’s shortcut system allows you to execute an action when a key is pressed and a different action when the key is released, enabling push-to-talk functionality. See Shortcuts for details.

VR

Jay supports leasing VR headsets to applications via the wp_drm_lease_device_v1 protocol.

Adaptive Sync

Jay supports adaptive sync (VRR) with configurable cursor refresh rates. See Outputs (Monitors) for per-output VRR settings.

Tearing

Jay supports tearing presentation for games. See Outputs (Monitors) for per-output tearing settings.

Low Input Latency

Jay uses frame scheduling to achieve input latency as low as 1.5 ms.

Color Management & HDR

Jay supports the Wayland color management protocol and HDR10 output with per-monitor color space, transfer function, brightness, and blend space controls. See HDR & Color Management for a full walkthrough.

Night Light

Jay supports night-light applications via the zwlr_gamma_control_manager_v1 protocol.

Window and Client Rules

Jay supports powerful, reactive window and client rules. Rules are re-evaluated whenever matching criteria change (e.g. a window’s title changes).

See Window & Client Rules for details.

Protocol Support

Jay supports a large number of Wayland protocols. Protocols marked as Privileged are only accessible to applications that have been explicitly granted access. See Granting Privileges for how to do this.

1. Cursors are always composited. ↩

2. Seat creation is always rejected. ↩

3. Sandboxes can restrict access to this protocol. ↩