Waypipe: graphical remote access for Wayland applications

2025-05-28T19:29:14-03:00

Tried out Waypipe</a> 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!</p>

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

waypipe</span> ssh user@server foot</span></span></code></pre>
(I’m using foot</a> 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).</em></small></p>
This failed with the following message:</p>
S2874:  0.603209 [src/server.c:649] Env. var XDG_RUNTIME_DIR not available, cannot place display socket for WAYLAND_DISPLAY="wayland-HBTrV7VT"</span></span></code></pre>
The issue here is that most (all?) Wayland applications expect at least XDG_RUNTIME_DIR</code> to be set, and a bare ssh connection will not set that on its own.</p>
The man page does mention this and how to fix it. It gives you several options, one of which is using ~/.ssh/environment</code> and setting it up properly at the client</a> and server</a>.</p>
Instead, I prefer to use the following approach because it’s isolated to each host instead:</p>
Client ~/.ssh/config</code>:</p>
Host <server></span></span>
    User <user></span></span>
    SetEnv XDG_RUNTIME_DIR=<user-writable-directory></span></span></code></pre>
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:</p>
S2889: 60.436704 [src/util.c:237] Error opening folder in which to connect to socket: Permission denied</span></span></code></pre>
If you’d rather reuse the XDG_RUNTIME_DIR</code> value you already have set on the client, you can also use SendEnv</code> instead of SetEnv</code>, 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</code>.</p>
Next, you need to make sure the server will allow the client to send this environment variable.</p>
Server /etc/ssh/sshd_config</code>:</p>
AcceptEnv XDG_RUNTIME_DIR</span></span></code></pre>
Make sure you have Waypipe installed on both server and client. Finally, from the client’s shell:</p>
waypipe</span> ssh user@server foot</span></span></code></pre>
That’s it! If all went well, a window should pop up with foot</code> — or whatever command you chose — running directly from the server.</p>

jutty.dev - wayland

Waypipe: graphical remote access for Wayland applications