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

XWayland and wlroots are pulled in as dependencies of Wayback.

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.
Neither an ~/.xinitrc executable nor the xinit package that supplies the /etc/X11/xinit/xinitrc executable are potentially necessary in many cases:-
- The usual X11 ~/.xinitrc file could be reviewed and used without even installing xinit, if one so chooses. However, it could be useful to cause other packages to autolaunch as part of the instructions in that file. Nevertheless, if the use of the .xinitrc/xinitrc ecosystem could be avoided, then the absence of such additional layer of complexity would be a preferred configuration.
- Wayback is hard-coded to look for ~/.xinitrc only whenever a session manager is not specified directly to the wayback-session i.e. if wayback-session or exec wayback-session is the sole instruction. In such cases, Wayback will search for ~/.xinitrc. If such file does not exist, Wayback will fall back to /etc/X11/xinit/xinitrc; in that case, the xinit package would be required to be installed so as to supply that executable.
- The same applies if Wayback is autolaunched e.g. through ~/.profile or through a display manager.

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 ~/.xinitrc or /etc/X11/xinit/xinitrc if customization/X11 package autostarts are used with such a facility.
for your X11 window manager with its own configuration/customization files.

.xinitrc

A previously used ~/.xinitrc file could be reviewed for conflicts and imported, or create one for the user to customize using a text editor. Wayback does not search for such a file using any user-specified configuration path, currently. ~/.xinitrc requires 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

Note: If /etc/X11/xinit/xinitrc were preferred to be customized instead of ~/.xinitrc, then the xinit package would supply that file:

$ doas apk add xinit

As this xinitrc file is already an executable, a chmod instruction similar to the above would not' be applicable.

Usage

Launching from a tty

From a tty without .xinitrc

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 .xinitrc

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 or /etc/X11/xinit/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 that Wayback only launches provided that no display server is already running and that it only runs once i.e. on a specific tty , tty1, as stated in that suggested code.

That code requires that ~/.xinitrc or /etc/X11/xinit/xinitrc be configured to specify and to launch the selected window manager. If such a facility is preferred not to be used, and if only one X11 window manager would ever be autostarted by Wayback using ~/.profile, then the exec wayback-session line will need to be expanded to specify the intended window manager e.g. exec wayback-session cwm .

Autostart from a display manager - without .xinitrc

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

As wayback-session is fed the session name in that fashion, i.e. Exec=wayback-session sessionname, no .xinitrc or xinitrc executable will be read, and any such executable 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 from a display manager - using .xinitrc

Alternatively to stating the session name in the .desktop's Exec=wayback-session sessionname line, the ~/.xinitrc or /etc/X11/xinit/xinitrc executables could be used and configured to select what window manager to launch depending on a variable conditional stated there: see example above using $HOSTNAME. A generic .desktop file to launch Wayback through the DM could be employed in that case, including shortening the line to Exec=wayback-session.

Autostart only one window manager from a display manager - .xinitrc optional

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. However, this would introduce an additional layer of complexity, requiring that the .xinitrc configuration steps above were followed in order to specify the intended window manager in that ~/.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.