This tool is slop-coded. Treat it as personal infrastructure rather than polished, generally supported software. Review the implementation and test it against your environment before relying on it.

waypipe-persist

waypipe-persist manages a reconnecting Waypipe connection between two Linux hosts.

It combines:

• a local systemd user service running the Waypipe client;
• an autossh reverse Unix-socket forwarding tunnel;
• a remote systemd user service running the Waypipe server; and
• sourceable Bash or Fish environment output that selects the Waypipe display and native Wayland backends.

The tunnel runs independently of the invoking terminal and reconnects after transient SSH failures. Setup is serialized per remote host, stale sockets are removed, and failed setup stops the transient tunnel.

Requirements

Both hosts must have:

• SSH connectivity and authentication configured;
• Waypipe installed;
• a running systemd user manager; and
• matching waypipe-client@.service and waypipe-server@.service units.

The executable package provides autossh, OpenSSH, systemd utilities, coreutils, and flock, but it does not install or configure the Waypipe user units.

The expected unit commands are equivalent to:

# Local waypipe-client@.service
ExecStart=waypipe --socket %t/waypipe-%i-client.sock client

# Remote waypipe-server@.service
ExecStart=waypipe --socket %t/waypipe-%i-transport.sock --display waypipe-%i server -- sleep infinity

Usage

Start, stop, or fully recreate a connection from the client host:

waypipe-persist start SERVER
waypipe-persist stop SERVER
waypipe-persist restart SERVER

start is idempotent: it leaves active services running and creates missing connection components. restart stops the local tunnel and Waypipe client plus the Waypipe server on the remote host, removes their sockets, and starts the connection from scratch.

On the server host, print sourceable environment settings for the client hostname:

source <(waypipe-persist env bash CLIENT)
waypipe-persist env fish CLIENT | source

The environment output unsets DISPLAY, sets WAYLAND_DISPLAY=waypipe-CLIENT, and selects native Wayland backends for common toolkits.

SERVER is passed to SSH, so aliases from ~/.ssh/config work. Discovered hostnames become parts of systemd instance names and Unix-socket paths; they must contain only letters, digits, _, ., or -. CLIENT must follow the same restriction.

Only one start, stop, or restart operation per local/remote hostname pair may run at once. After setup, the tunnel remains managed by the local systemd user manager as waypipe-tunnel-<remote-host>.service.

Nix flake

Build the package:

nix build

Run it directly:

nix run . -- start SERVER

Consume its overlay:

{
  inputs.waypipe-persist.url = "...";

  nixpkgs.overlays = [ inputs.waypipe-persist.overlays.default ];
}

The flake supports x86_64-linux and aarch64-linux, and exports packages.<system>.waypipe-persist plus the default package.

Testing

shellcheck waypipe-persist.sh tests/run.sh
nix flake check

The tests replace SSH and systemd commands with local fakes. They do not contact hosts or mutate user services.

License

Copyright © 2026 Alexander Khodyrev.

Licensed under the GNU Affero General Public License, version 3 or later. See COPYING.