Wayback

Wayback is an X11 compatibility layer that enables hosting a full X11 desktop environment on Wayland. It acts as a minimal (stub) compositor that enables Xwayland to run in rootful mode, i.e. Xwayland owning the root window, which then behaves like a full X11 server. This is unlike Xwayland run without Wayback, as it then acts as an X server running as a client on Wayland and can then only enable certain X11 applications during a Wayland session. As one of the benefits of Wayback supplying a dedicated X11 server environment, it can run applications originally developed for X11 that cannot operate correctly under rootless Xwayland.

The aim is to eventually make Wayback "a drop-in replacement to the Xorg binary". This may imply a limited need to amend user configurations/session scripts such as .xinitrc and reducing the maintenance burden in development. Wayback uses wlroots and Xwayland, and its 0.3 release is of alpha quality. It is available in the community repositories of Alpine Linux Edge and v3.23. v3.23.x

Note that Wayback cannot be launched from within a Wayland compositor (e.g. from Sway or river-classic/River): both need complete control of the graphics stack by their nature as display servers/compositors.

Prerequisites

The community repository must be enabled.
A seat manager - elogind or seatd enabled in openrc init installations. Although systemd-logind is an alternative listed in the FAQs upstream, this package is not available on Alpine Linux as of December 2025; enabling Elogind should suffice when employing Wayback with systemd on Alpine Linux – not tested for wiki.
An X11 window manager or X11-based desktop: see Desktop environments and Window managers.
xinit would be useful only if launching and customizing (an) X11 window manager(s) under that facility. If a display manager is used to autolaunch Wayback sessions for more than one window manager in turn, then xinit would not be invoked and would be redundant; see the xinit configuration and Autostart sections.

Installation

To install Wayback, plus the -doc man pages for Xwayback and wayback-session with the license agreement:

$ doas apk add wayback wayback-doc

To launch, say, the cwm window manager in a Wayback session, install it first:

$ doas apk add cwm

Configuration

The immediate required configuration would be:-

for xinit where customization is desired using that facility; and if a single X11 window manager is expected to be launched.
for your X11 window manager with its own configuration/customization files.

xinit

Install xinit:

$ doas apk add xinit

Create an ~/.xinitrc file for the user to customize using a text editor, and add a shebang line (#!/bin/sh) at the top. For example, to enable the Right Alt key as the Compose key, one could install setxkbmap, and then edit as follows:

Contents of ~/.xinitrc

#!/bin/sh
/usr/bin/setxkbmap -option compose:ralt &

Add a line to launch the window manager (cwm in our example) as the last line being read in that file:

exec cwm

Alternatively, that line could be replaced to enable different window managers, say, depending on a variable of your choosing, such as $HOSTNAME, provided that the other window managers have been configured also. For example, the line could be replaced by:

if [ "$HOSTNAME" = "work" ]; then
    exec startxfce4
else
    exec cwm
fi

Make the file executable by the user:

$ chmod 700 ~/.xinitrc

Usage

Launching from a tty

From a tty without xinit

A Wayback session may be launched from a tty user prompt – never as root for the sake of security – simply by running wayland-session followed by the window manager launcher name, instead of startx followed by the window manager launcher name and its path, as used in X11. From man wayback-session:

wayback-session optionally takes the command to launch a session.

Therefore, to illustrate with cwm as the window manager, from a tty as user:

$ wayland-session cwm

From a tty using xinit configurations

Continuing on from the passage above in man wayback-session:

If no command is specified it will try to launch ~/.xinitrc. If ~/.xinitrc is not found, it will launch /etc/X11/xinit/xinitrc.

In that fashion, once ~/.xinitrc is installed and configured, then, from a tty as user – never as root for the sake of security:

$ wayland-session

Autostart

Autostart from .profile

wayback-session may be autostarted from ~/.profile provided that safeguards are taken to avoid errors or infinite loops. To this end, the following could be added at the end of your ~/.profile :

if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
    exec wayback-session
fi

This test ensures: (a) a launch test in ~/.profile to deny starting X within another session by testing with if [ -z "$DISPLAY" ]); and (b) that wayback-session only runs once i.e. on a specific tty , tty1, as stated in that suggested code.

This code requires that xinit be configured to launch the selected window manager. If xinit is not desired to be installed and only one window manager would be launched, then the line exec wayback-session will need to be expanded to specify the intended window manager e.g. exec wayback-session cwm .

Autostart from a display manager - xinit redundant

A display manager e.g. SDDM, LXDM or SLiM may be configured to autostart one or more window managers at a time under Wayback.

Create a file e.g. /usr/share/xsessions/wayback-cwm.desktop with contents such as:

Contents of /usr/share/xsessions/wayback-cwm.desktop

[Desktop Entry]
Name=Wayback-cwm
Exec=wayback-session cwm
Type=Application
DesktopNames=Wayback
Comment=cwm running under Wayback

No xinit file will be read if a session name is specified in the fashion above (i.e. Exec=wayback-session sessionname). In that case, xinit would be redundant.

Make the file readable by all and writable by root only:

$ doas chmod 644 /usr/share/xsessions/wayback-cwm.desktop

On reboot, select Wayback-cwm from the display manager session dropdown menu.

The process could be repeated for other window managers, say, for XFCE, which would be particularly useful while it is transitioning to Wayland if sought to be launched using Wayland: Xfwm could benefit from Wayback, for example, first by creating a /usr/share/xsessions/wayback-xfce.desktop file, and then repeating the steps above.

Contents of /usr/share/xsessions/wayback-xfce.desktop

[Desktop Entry]
[Desktop Entry]
Name=Wayback-XFCE
Exec=wayback-session startxfce4
Type=Application
DesktopNames=Wayback
Comment=XFCE running under Wayback

Autostart only one window manager from a display manager - xinit required

In case only one X11 window manager is expected to be launched on the system, with or without Wayback, then the Exec=wayback-session cwm line in /usr/share/xsessions/wayback-cwm.desktop and all other lines, plus that filename, could be shortened to omit the mention of cwm. This would require that the xinit configuration steps above were followed in order to specify the intended window manager in the ~/.xinitrc file instead.

Further steps

Development is seeking to improve from Xwayland’s rootful mode by eventually deploying Wayback in an arguably safer rootless mode in order to facilitate proper multi-monitor support and other facilities. As may be typical of alpha releases, Wayback currently has no DPMS/power management and lacks certain Xorg options.