Skip to content

Waypipe: graphical remote access for Wayland applications

Tried out Waypipe today as a way to remotely control graphical Wayland applications between Alpine Linux and FreeBSD hosts and it’s snappy on my wireless network + decade-old hardware combo!

At first, the minimal example given by Waypipe in its README and man page did not work:

waypipe ssh user@server foot

(I’m using foot as the example here because that’s the terminal I use on both systems, but it could be anything — a simplistic application, a web browser or even a full-blown compositor).

This failed with the following message:

S2874:  0.603209 [src/server.c:649] Env. var XDG_RUNTIME_DIR not available, cannot place display socket for WAYLAND_DISPLAY="wayland-HBTrV7VT"

The issue here is that most (all?) Wayland applications expect at least XDG_RUNTIME_DIR to be set, and a bare ssh connection will not set that on its own.

The man page does mention this and how to fix it. It gives you several options, one of which is using ~/.ssh/environment and setting it up properly at the client and server.

Instead, I prefer to use the following approach because it’s isolated to each host instead:

Client ~/.ssh/config:

Host <server>
    User <user>
    SetEnv XDG_RUNTIME_DIR=<user-writable-directory>

The directory above must exist prior to the connection and must be writable by the user as whom we will ssh into the server. Otherwise, it will throw the following error:

S2889: 60.436704 [src/util.c:237] Error opening folder in which to connect to socket: Permission denied

If you’d rather reuse the XDG_RUNTIME_DIR value you already have set on the client, you can also use SendEnv instead of SetEnv, but their values may not be interchangeable. In my case, Alpine and FreeBSD use different directories with different permissions. This is one other advantage of this method over ~/.ssh/environment.

Next, you need to make sure the server will allow the client to send this environment variable.

Server /etc/ssh/sshd_config:

AcceptEnv XDG_RUNTIME_DIR

Make sure you have Waypipe installed on both server and client. Finally, from the client’s shell:

waypipe ssh user@server foot

That’s it! If all went well, a window should pop up with foot — or whatever command you chose — running directly from the server.