mwb-linux

README

Share your keyboard, mouse, and clipboard seamlessly between Linux and Windows.

Features • Installation • Quick Start • How It Works • Configuration • Contributing

---

What is this?

MWB Linux is a native Linux client that connects to Microsoft PowerToys Mouse Without Borders on Windows. Move your mouse to the edge of the screen, and it seamlessly jumps to the other machine — along with your keyboard and clipboard.

flowchart LR
    A["🐧 <b>Linux PC</b><br/>Mouse · Keyboard"] <-->|" 🖱️ Mouse · ⌨️ Keyboard · 📋 Clipboard "| B["🪟 <b>Windows PC</b><br/>Mouse · Keyboard"]

Move your mouse to the screen edge — the cursor seamlessly jumps to the other machine.

No extra software needed on Windows beyond PowerToys, which bundles Mouse Without Borders.

Features

• Bidirectional mouse sharing — Control both machines from either keyboard/mouse
• Seamless edge switching — Move cursor to screen edge, it appears on the other machine
• Clipboard sync — Copy text or images on one machine, paste on the other
• Keyboard forwarding — Type on your Linux keyboard, text appears on Windows
• Full mouse support — Scroll wheel, horizontal scroll, and side buttons (back/forward)
• Encrypted — AES-256-CBC encryption with PBKDF2 key derivation
• Device isolation — When controlling Windows, your Linux cursor doesn't move
• Dual-mode connection — Acts as both server and client for fast reconnection
• Zero config on Windows — Works with existing PowerToys MWB setup
• Lightweight — Single binary, ~5MB, no GUI dependencies

Demo

Direction	What happens
Mouse hits left edge on Linux	Cursor appears on Windows, Linux input disabled
Mouse hits right edge on Windows	Cursor returns to Linux, input restored
Ctrl+C on Windows	Text/image available on Linux clipboard
Ctrl+C on Linux	Text/image available on Windows clipboard
Type on Linux keyboard	Text appears in focused Windows app

Installation

One-Line Install (Ubuntu/Debian)

curl -fsSL https://raw.githubusercontent.com/lucky-verma/mwb-linux/main/scripts/install.sh | sudo bash

From .deb Package

Download the versioned .deb for your architecture from Releases, then install it:

sudo dpkg -i mwb-linux_*_amd64.deb

# Add yourself to the input group
sudo usermod -aG input $USER

From Binary

# Download binary
wget https://github.com/lucky-verma/mwb-linux/releases/latest/download/mwb-linux-amd64
chmod +x mwb-linux-amd64
sudo mv mwb-linux-amd64 /usr/local/bin/mwb

# Install dependencies
sudo apt install xdotool xinput xclip

# Setup permissions
sudo bash -c 'modprobe uinput && echo uinput > /etc/modules-load.d/uinput.conf'
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-mwb-uinput.rules
sudo udevadm control --reload-rules
sudo usermod -aG input $USER

From Source

git clone https://github.com/lucky-verma/mwb-linux.git
cd mwb-linux
make build
sudo make install

Note: Log out and back in after installation for group changes to take effect.

Quick Start

1. Get the security key from Windows

Open PowerToys → Mouse Without Borders → copy the Security Key.

2. Configure

mkdir -p ~/.config/mwb
cat > ~/.config/mwb/config.toml << EOF
host = "192.168.1.100"        # Your Windows machine's IP
key = "YourSecurityKey"       # From PowerToys MWB
name = "linux"                # This machine's name (max 15 chars)
EOF

3. Run

# Receive only (Windows controls Linux)
mwb

# Bidirectional (Linux also controls Windows)
sudo mwb -bidi -edge left

4. Add your Linux machine on Windows

In PowerToys MWB, enter the security key and device name to connect.

How It Works

MWB Linux implements the full Mouse Without Borders protocol:

1. Dual-mode connection — Listens on port 15101 AND connects outbound (first one wins)
2. Handshake — AES-256-CBC encrypted challenge-response with PBKDF2-SHA512 key derivation
3. Heartbeats — Proactive keepalive every 5s prevents Windows from dropping the connection
4. Edge detection — 10ms cursor polling detects screen edges, instant switching with bounce prevention
5. Input forwarding — Mouse (absolute coords) and keyboard (VK codes) sent as MWB packets
6. Device isolation — xinput disable/enable prevents dual cursor movement during remote control
7. Clipboard — Bidirectional text/image sync via compressed clipboard packets

For detailed protocol documentation, see docs/ARCHITECTURE.md.

Configuration

config.toml

Field	Default	Description
host	(required)	Windows machine IP address
key	(required)	MWB security key (from PowerToys)
name	hostname	This machine's display name
port	15100	Base port (message port = 15101)
remote_width	1920	Remote screen width in pixels
remote_height	1080	Remote screen height in pixels
edge	left	Screen edge for switching: left or right
clipboard	true	Clipboard sync: set false to disable text/image sharing
accel_multiplier	2.0	Cursor speed when controlling Windows. Lower it (e.g. 1.0, 0.5) if the Windows cursor feels too fast
inbound_multiplier	1.0	Cursor speed when Windows controls Linux. 1.0 mirrors Windows exactly; raise it for faster inbound movement

CLI Flags

Flag	Default	Description
-bidi	false	Enable bidirectional input (Linux → Windows)
-edge	(from config)	Override edge from config: left or right
-no-clipboard	false	Disable clipboard sharing (overrides config)
-debug	false	Enable debug logging
-config	~/.config/mwb/config.toml	Config file path

Windows Side Requirements

• PowerToys installed with Mouse Without Borders enabled
• "Move mouse relatively" set to OFF (required for bidirectional mode)
• "Share clipboard" set to ON (for clipboard sync)
• "Block screen saver on other machines" set to ON (recommended, keeps connection alive)
• Security key shared with Linux client
• Windows Firewall must allow ports 15100-15101 (TCP inbound/outbound)

Troubleshooting

"permission denied" on /dev/uinput

Run the setup permissions commands above, then log out and back in.

Clipboard not syncing

Ensure xclip is installed: sudo apt install xclip

Disable clipboard sharing

Set clipboard = false in config.toml, or run with -no-clipboard. The Linux client then never reads or writes the local clipboard, so it won't override what you copied on Windows.

Mouse controls both screens simultaneously

Run with -bidi flag and sudo for device isolation via xinput.

Connection refused

• Check Windows firewall allows port 15100-15101
• Verify the IP address in config.toml
• Ensure PowerToys MWB is enabled on Windows

Cursor bounces back immediately

Set "Move mouse relatively" to OFF in PowerToys MWB settings.

Project Structure

cmd/mwb/              CLI entry point
internal/
  capture/            Edge detection, evdev capture, xinput device isolation
  clipboard/          Bidirectional clipboard sync (text + images)
  config/             TOML configuration
  input/              Virtual mouse/keyboard via uinput
  network/            TCP connection, encryption, packet send/receive
  protocol/           MWB packet types, serialization, AES-256-CBC
docs/
  ARCHITECTURE.md     Detailed protocol and architecture documentation
scripts/
  install.sh          Installation helper script

Known Limitations

• Keyboard on Windows lock screen — Keyboard input may not work on the Windows lock screen (Winlogon desktop security restriction)
• Middle mouse button auto-scroll — Middle-click auto-scroll (scroll lock mode) does not work in browsers; normal middle-click works
• First connection — Initial handshake takes ~3-16s depending on Windows MWB state; subsequent reconnects are instant
• Bidirectional mode requires X11 — Edge detection and device isolation use xdotool/xinput. Receive-only mode works on Wayland (XWayland session). Native Wayland bidirectional support requires compositor extensions and is not yet implemented.
• Brief screen stall on return with many input devices — Device isolation re-enables every matched device via xinput when control returns to Linux. On setups with many input devices (e.g. several gaming peripherals exposing 15+ xinput sub-devices) the compositor can stall for ~1-2s on return (the cursor keeps moving, the screen briefly freezes). An EVIOCGRAB-based isolation was tried to avoid this but introduced a worse cursor regression and was reverted; a proper fix (EVIOCGRAB done right, or libei) is tracked for a future release.
• Cursor speed / drift — Remote cursor movement scales raw evdev deltas by accel_multiplier (default 2×); lower it if the Windows cursor feels too fast (the Windows side adds no acceleration of its own). Tracking is open-loop, so the virtual cursor may still drift from the actual position over long sessions.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Building

make build    # Build binary
make test     # Run tests
make lint     # Run linter
make check    # All of the above

Acknowledgments

• Microsoft PowerToys — Mouse Without Borders is part of PowerToys (MIT License). This project implements the MWB network protocol for Linux.
• bketelsen/mwb — Initial Go implementation of the MWB receive-only client that this project builds upon.
• The MWB protocol specification was derived from the open-source PowerToys codebase.

License

MIT License — see LICENSE for details.