Install & configure

Requirements

betterkvm is peer-to-peer: every machine runs the same daemon, there is no master or server. Here's what each platform captures input with, injects with, and needs from you.

Install · Linux

Grab the .deb, .rpm, or AppImage for your distro and install it. The package drops in betterkvm and the layout editor, adds the udev rule for input access, and installs a background user service.

# Debian / Ubuntu
$ sudo apt install ./betterkvm_1.0.0_amd64.deb

# Fedora / RHEL
$ sudo dnf install ./betterkvm-1.0.0.x86_64.rpm

# add yourself to the input group (one-time), then start it
$ sudo usermod -aG input $USER     # then log out and back in
$ betterkvm init
$ systemctl --user enable --now betterkvm

Install · macOS

Download the .dmg, drag betterkvm to Applications, and launch it. Grant two permissions the first time so it can capture and inject input.

# 1. Open betterkvm.dmg and drag betterkvm to Applications
# 2. Launch it, then in System Settings -> Privacy & Security allow:
#      - Accessibility
#      - Input Monitoring
# 3. Quit and reopen betterkvm to apply

Install · Windows

Run the signed installer for Windows 10 or 11. It drops in betterkvm and the layout editor and registers a background service — no extra permission prompts.

# 1. Run betterkvm-setup.msi and follow the installer
# 2. betterkvm and the layout editor land in the Start menu
# 3. The background service starts at login automatically
#    No extra permissions are required.

Configuration

Config lives at ~/.config/betterkvm/config.toml. Print the exact path with betterkvm config-path, or create a commented example with betterkvm init. Each machine describes its own neighbors, so configure both sides.

# ~/.config/betterkvm/config.toml

name = 'fedora'                  # shown to peers; defaults to hostname
password = 'your-shared-secret'  # enables AES-256-GCM; match on every machine

[[peers]]
name   = 'mac1'
side   = 'up'        # left | right | up | down
anchor = 'DP-1'      # optional: attach to ONE monitor's edge
align  = 'center'    # optional: start | center | end

side

Maps the peer to the whole desktop edge — fine for two machines.

anchor

Pins the peer to one monitor's edge (connector name from xrandr, or index). Essential for multi-monitor desks.

align

Where along that edge the peer starts: start, center, or end.

Layout editor

The easiest way to arrange your desk is the GUI. It renders your real monitors and configured peers to scale — drag a peer to any monitor edge and click Save to write the config.

$ betterkvm-layout

Usage

Under the installed service managers the daemon runs automatically at login. You can also drive it directly:

$ betterkvm run                          # run the daemon in the foreground
$ betterkvm send mac1 photo.jpg doc.pdf  # send files to a connected peer
$ betterkvm init                         # write an example config
$ betterkvm config-path                  # print the config file location
$ betterkvm-layout                       # visual layout editor

Logs & received files

Received files — from send or a clipboard file paste — arrive in ~/Downloads/betterkvm/ on the receiving machine. Daemon logs live with your service manager:

# Linux
$ journalctl --user -u betterkvm

# macOS
$ tail -f /tmp/betterkvm.out.log /tmp/betterkvm.err.log