Linux-to-Linux keyboard/mouse forwarding over ssh. Type/click on host B, have the events land on host A. ssh is just the pipe carrier; the wire format is HID-shaped so non-Linux ends can be added later without a protocol break.
uv sync
uv run evpipe-send --help
uv run evpipe-recv --help
Sender needs read+grab access to the source /dev/input/event* nodes
(usually the input group). Receiver needs read+write on /dev/uinput.
uv run evpipe-send --list-devices # pick paths
uv run evpipe-send --kb /dev/input/eventXX | uv run evpipe-recv
Press a few keys on the source kb. They appear on the receiver's
virtual evpipe: <name> uinput device (visible in xev / Wayland's
key logs). Ctrl-C either end -- the grabs are released cleanly.
Run the receiver on host A (where you want the input to land), the sender on host B (where the physical kb/mouse lives):
# On A:
ssh -o ServerAliveInterval=5 -o ServerAliveCountMax=2 \
user@B 'evpipe-send --kb /dev/input/event3 --mouse /dev/input/event7' \
| evpipe-recv
ServerAliveInterval=5 ServerAliveCountMax=2 makes A's ssh give up on
a stalled link within ~10s instead of waiting for TCP. It frees A, not
B: the sender on B only learns the session is dead when sshd there
notices, which on a half-open connection takes ~15 minutes. Three
things in the sender bound that instead:
- Newest sender wins. On start,
evpipe-sendtakes an flock on$XDG_RUNTIME_DIR/evpipe-send.lock(--lock-fileto change or disable). A previous holder is sentSIGTERM(its ungrab path), thenSIGKILLif it does not go within 2s; the kernel releases the grab when the fd closes. So reconnecting after a dead session never shares B's keyboard with the stale sender. One sender per user per host. - Exit on suspend. If B itself slept for longer than ~10s, the session is presumed dead and the sender exits on resume rather than hold the grab until TCP times out.
- Exit on stalled output. The sender never blocks on its stdout. If sshd stops draining it and the buffers in between fill up, the sender exits. Until then the toggle chord keeps working, so B's keyboard is never stuck behind a dead link. This is a backstop, not a detector: with little traffic the buffers take a long time to fill.
--toggle-chord takes a comma- or plus-separated list of evdev key
names. The last key is the trigger; the rest must be held when it
transitions to pressed. The trigger event is consumed (never reaches A),
and the chord works whether forwarding is currently ON or OFF -- so it
also serves as the bailout when B's keyboard is grabbed.
The default is KEY_F10 -- a single dedicated key, no modifiers, no
QMK-layer/tap-hold complications. Pass an empty string to disable
toggling entirely (always-on, kill the ssh to bail out). If a chord
isn't firing, run the sender with --log-level=DEBUG; the log shows
which modifiers were missing when the trigger pressed.
ssh user@B '
evpipe-send --kb /dev/input/event3 --mouse /dev/input/event7 \
--toggle-chord KEY_F10 \
--start-off
' | evpipe-recv
--start-off is useful when you want B's keyboard to start out
local-only and flip into forwarding mode only after you press the chord.
Forwarding never begins in the middle of a keystroke. At startup, and when toggling ON, the sender waits until every key and button on the source devices is released before it grabs them, so nothing is left stuck down on B or pressed out of nowhere on A.
Once forwarding is ON the sender holds EVIOCGRAB, so B's compositor
sees nothing from the keyboard and its own key bindings go dead. To keep
a specific local hotkey alive in that state, --action-chord CHORD:COMMAND runs a shell command when the chord fires, using the same
detection path as the toggle chord. It fires only while grabbed -- when
ungrabbed, B's compositor still sees the key and runs its own binding, so
firing here too would double-trigger. The trigger key is consumed (never
forwarded). Repeatable; triggers must be distinct.
evpipe-send --kb /dev/input/event3 \
--action-chord 'KEY_LEFTMETA+KEY_D:echo toggle > $XDG_RUNTIME_DIR/dictate.fifo'
With a bare-modifier chord like Super+D, the modifier is forwarded to A
before the trigger reveals the chord, so A sees a lone Super tap (which
opens the GNOME overview, etc.). --local-only KEY_LEFTMETA keeps that
modifier out of the wire entirely -- it still counts toward chord
matching but is never forwarded nor put in the resync snapshot. The
tradeoff is that the key is then unusable on A (no Super+Tab); if you
need it there, use a bare-key action chord instead.
--dictation-socket PATH opens a local unix socket that accepts one JSON
object per line, {"text": "...", "submit": bool}, and replies
{"routed": "remote"} or {"routed": "local"}. While forwarding is ON
the text is typed on the receiver (converted to key events on the first
keyboard source -- no extra virtual device on either host); while OFF the
sender replies local so the caller types it itself. This pairs with
whisper.cpp's dictate.py --emit-socket: one dictation setup follows
your focus, typing on A when you're driving A and locally via wtype
when you're not. Only US-layout printable characters survive the remote
path (accented letters/emoji have no HID key and are dropped).
- Keyboard keys on the HID Keyboard usage page (a-z, 0-9, modifiers, function keys, navigation, numpad, common consumer media keys).
- Mouse buttons 1-8 (left, right, middle, side, extra, forward, back, task).
- REL_X, REL_Y, REL_WHEEL, REL_HWHEEL (incl. hi-res variants).
Anything outside the static hid_map table is dropped at the sender;
--log-level=DEBUG there logs each dropped key press. EV_ABS (tablets, touchscreens) is reserved in
the wire format but not yet wired in either direction.
packaging/evpipe.service is the ssh pipeline above wrapped in a
systemd user unit, with the sender arguments in
~/.config/evpipe/evpipe.conf. See packaging/README.md.