kvshare

Share keyboard and mouse input from macOS to Linux over a local network.

Install

Versioned releases provide a macOS .pkg and an Arch Linux package that install without a repository checkout. Verify the published checksums, then follow the macOS installation guide and Arch Linux installation guide.

Build from source

Development requires Rust 1.88+, Swift 6.2+ on macOS, GNOME Shell on Wayland, and a fixed wired Ethernet route between the target machines.

cargo build
swift build --package-path swift --product KvshareMac

Development

Run the current Rust application directly with cargo run.

macOS menu-bar app

For a stable release installation, permissions, optional login launch, operation, and recovery, follow docs/MACOS_APP.md.

For development, create the fixed receiver configuration:

mkdir -p ~/.config/kvshare
cp config/kvshare.example.json ~/.config/kvshare/config.json

Then run the menu-bar app:

swift run --package-path swift KvshareMac

Set KVSHARE_CONFIG to load a different configuration path. The app starts disabled; use its menu-bar icon to enable or disable sharing, inspect status, or quit. On first enable, grant both Input Monitoring and Accessibility access in System Settings, then disable and enable kvshare again. While Linux has control, press Control-Option-Escape to return control to the Mac.

Cursor-capture regression check

1. Enable sharing and push through the Mac display's right edge.
2. Move the mouse while Linux has control and verify that Linux receives movement while no cursor is visible moving on the Mac. If number mirroring is enabled, verify that unmodified top-row numbers still reach both machines.
3. Return through Linux's left edge and verify that the Mac cursor is visible, parked at the right edge, and moves normally.
4. Repeat the handoff and return with Control-Option-Escape, receiver disconnect, Disable, and Quit; each path must restore normal Mac cursor visibility and movement.

Run formatting, linting, and tests before submitting changes:

make check

Run all pre-PR checks before opening a pull request:

make pre-pr

List the available Make targets with make help.

Packaging and releases

Cargo.toml is the canonical semantic version source. Run make package-macos on macOS or make package-arch on Arch Linux to build local artifacts. Tagged Forgejo releases build and publish both packages and SHA-256 checksums. See docs/RELEASES.md for versioning, release creation, signing, and verification.

Setup and verification

For a clean target-machine setup:

1. Install the Linux receiver service, including uinput access and fixed source-IP configuration.
2. Install the GNOME handoff extension, then log out and back in when required.
3. Install and authorize the macOS app.
4. Follow the smoke tests in the platform guides and compare with the MVP verification results.

License

MIT