Configuration Xwayland

X11 support (xwayland-satellite)

Ferese can run legacy X11-only applications through xwayland-satellite.

xwayland {
    enabled #true
    startup  on-demand
    path     "xwayland-satellite"
}

Key	Values	Default	Meaning
enabled	true / false	true	Run the bridge at all. false is a complete opt-out.
startup	on-demand / eager	on-demand	on-demand starts Satellite the first time an application connects to the X11 socket. eager starts it during session startup.
path	path to an executable	xwayland-satellite	Which binary to run.

These keys require a new session. Reloading configuration does not restart or reallocate the X11 service; feresectl xwayland status reports restart_required when the running configuration no longer matches the file.

Requirements and failure behavior

xwayland-satellite and an Xwayland binary it can find must be installed. Satellite must be built with its systemd feature enabled (cargo build --release --features systemd); that feature sends the READY=1 notification Ferese waits for. Upstream's default feature set is empty, so a default build never sends it and every start ends in a startup failure after Ferese's fixed 10-second budget, even though the process is running. Being spawned is not readiness. If any of these are missing, the session still starts as a normal Wayland desktop and feresectl xwayland status explains why X11 is unavailable. Ferese never publishes a DISPLAY value that does not work, so applications fail cleanly instead of hanging against an endpoint that accepts nothing.

In a nested session, Ferese's own environment is preserved for backend initialization, but applications it launches receive the new Ferese endpoints. The host's DISPLAY is never exported to the activation environment of a nested session, so it cannot leak into services started by your login session.

Diagnostics and recovery

feresectl xwayland status
feresectl xwayland retry

status reports whether the service is idle, starting, running, backing off, or failed, plus the display, the Satellite PID, and whether readiness was verified. A failed service is not restarted automatically: Ferese retries a small bounded number of times, then stops and waits, so a broken binary cannot produce a restart loop. Run feresectl xwayland retry once the cause is fixed. The snapshot never contains the X11 cookie, so it is safe to paste into a bug report.

retry can also refuse to run. If the previous service group cannot be proven gone — for example it survived the stop sequence — Ferese keeps its cleanup record instead of starting a second generation that would compete with survivors for the same display, and the retry fails with a message naming what still holds the X11 display. The endpoint is not republished in the meantime. Run the retry again once that group has finished exiting.

Each start uses a fresh, private notification socket and only a READY=1 message from the Satellite process that was actually spawned is accepted, so a stale or unrelated notification cannot be mistaken for readiness.

Limitations

• X11 applications are ordinary Wayland windows as far as layout, focus, and window rules are concerned. Rules match the application identity Satellite reports, so they are configured the same way as for native clients.
• Native Wayland preferences are kept as they are. Ferese does not force GTK, Qt, Firefox, or Electron onto X11 to demonstrate support.
• Portal dialogs requested with an x11: parent are shown unparented. The chooser or consent prompt still opens and authorization is unchanged; Ferese does not yet translate an X11 window ID into a Wayland export, and inventing a parent would be a security problem.
• Per-monitor fractional scaling of X11 applications depends on the selected Satellite build and its Xsettings policy. Text sharpness, pointer coordinates, and popup placement should be checked on each output profile rather than assumed.
• Drag and drop between native and X11 applications depends on the Satellite build and is not part of the initial support claim.
• Sandboxed applications may need explicit permission to reach the display. A flatpak with only fallback-x11 gets no X11 socket inside a Wayland session and cannot read the private XAUTHORITY file under $XDG_RUNTIME_DIR, so it exits without a window while the service itself reports healthy. See Sandboxed applications.