Beamer Explained: Open-Source Software KVM for Mac, Windows & Linux

Every engineer who runs a dual-machine workstation knows the desk-clutter tax. You have a sleek MacBook Pro for compile-heavy frontend code and communications, sitting right next to a high-powered Windows desktop or Linux box for heavy GPU workloads, gaming, or local model fine-tuning.

Your desk ends up choked with two mechanical keyboards, two mice, or an ugly tangle of USB switcher cables.

Hardware KVM (Keyboard, Video, Mouse switch / physical hardware box switching peripheral cables between computers) switches solve this in theory, but fail in practice. Physical KVMs cost hundreds of dollars, introduce input latency, wreck high-refresh-rate monitor signals, and throw fits whenever Bluetooth peripherals disconnect.

Apple solved this beautifully with Universal Control, but Apple built a walled garden. Universal Control will never run on Windows or Linux. Meanwhile, legacy open-source alternatives like Barrier, Synergy, or Deskflow carry two decades of legacy C++ baggage: fragile server-client configurations, manual IP address typing, broken TLS certificates, and frequent clipboard lockups.

Independent engineer Toby Kalkman created kalkman-code/beamer: a modern, zero-account, open-source software KVM that shares a single keyboard, mouse, and clipboard seamlessly between Mac, Windows, and Linux over your local network.

TL;DR

Quick Answer Box (Google Search Featured Snippet):

• What is Beamer? An open-source software KVM switch utility created by Kalkman Code that allows one physical keyboard, mouse, or trackpad to control multiple Mac, Windows, and Linux computers across a local network with zero external cloud relays.
• Core Architecture: Peer-to-peer Wire Protocol v6 built on ephemeral X25519 key exchange, HKDF-SHA256 session key derivation, ChaCha20-Poly1305 authenticated per-frame encryption, and screen edge physics.
• Primary Breakthrough: Replaces cumbersome IP configurations with 6-digit code pairing, provides seamless trackpad acceleration curves, synchronizes clipboard text and images with decompression bomb protection, and operates entirely below Windows ephemeral port collision ranges.
• Official Repository: kalkman-code/beamer on GitHub · GNU GPL-3.0 License.

Repository: kalkman-code/beamer

Beginner Map (Mental Model)

Before inspecting the cryptographic handshake and packet frames, consider this physical analogy: using multiple computers on one desk without a software KVM is like having two separate notebooks sitting side-by-side, each chained to its own dedicated fountain pen. Every time your eyes shift from the left notebook to the right one, your hand must drop the first pen, reach across your desk, pick up the second pen, and adjust your posture.

Beamer acts like a frictionless magnetic conveyor belt embedded underneath your desk mat. When your pen glides off the right edge of the MacBook screen, the desk surface senses the pressure, lights up a subtle border highlight, and hands the pen seamlessly to the Windows display.

The interactive Markdy diagram below illustrates this operational lifecycle: from 6-digit peer pairing and ephemeral cryptographic key agreement to real-time input event streaming and clipboard staging.

Part 1: Foundations (The Multi-OS Desk Friction)

Developers rarely run multiple operating systems out of vanity. Modern software engineering enforces specialized operating systems for specific tasks. You draft designs in Figma and review Xcode builds on macOS because Apple silicon laptops offer all-day battery life and quiet fans. At the exact same desk, you run local LLMs (Large Language Models / artificial intelligence neural networks running on local hardware), train PyTorch models, or compile Unreal Engine shaders on a dedicated Windows or Linux desktop packed with an Nvidia RTX graphics card.

The historical solutions to bridge these systems present painful engineering compromises:

1. Physical KVM Switches: Premium USB-C and DisplayPort KVM boxes cost between $200 and $600. Beyond the price tag, they introduce physical cable clutter. Switching takes 2 to 4 seconds while monitor handshakes reset, and wireless mouse polling rates drop noticeably.
2. Logitech Flow: Logitech Flow lets users glide cursors across machines, but it demands an all-Logitech peripheral ecosystem. Furthermore, it requires running Logi Options+, an Electron-based daemon (background process operating without a graphical interface) that frequently consumes 300MB to 500MB of RAM and introduces noticeable edge-crossing stutter.
3. Synergy, Barrier, and Deskflow: Deskflow (formerly Barrier and Synergy) remains the grandfather of open-source KVMs. However, configuring Deskflow requires manual server and client IP assignments, generating self-signed TLS certificates, and configuring monitor grids by hand. If your router reassigns an IP address via DHCP (Dynamic Host Configuration Protocol / local network automated IP assignment service), the link severs.

Beamer was built to scrap this configuration friction. It treats multi-machine peripheral sharing not as an IT network administration task, but as a lightweight, zero-configuration local network link.

Part 2: Architecture & Wire Protocol (How Beamer Bridges Machines)

Under the hood, Beamer discards bloated dependencies. Its core network protocol is codified in core/protocol.py, implementing Wire Protocol v6. Unlike legacy tools that treat connections as static client-server hierarchies, Beamer establishes symmetric peer-to-peer links.

1. Ephemeral X25519 Handshake with Forward Secrecy

When two machines link, security cannot rely on plain tokens. If an attacker records local Wi-Fi packets and later recovers a static machine token, a legacy tool exposes all historic keystrokes.

Beamer enforces forward secrecy (cryptographic guarantee that historic recorded sessions cannot be decrypted even if long-term credentials leak later) using ephemeral X25519 (elliptic-curve Diffie-Hellman key exchange algorithm):

Host A (Initiator)                                 Host B (Responder)
       |                                                  |
       |  Preamble: WIRE_MAGIC (BEAMY) + Version (6)      |
       |  + Fresh Nonce Prefix (8 bytes)                  |
       |  + Ephemeral X25519 Public Share                 |
       | -----------------------------------------------> |
       |                                                  |
       |  Preamble: WIRE_MAGIC + Version + Nonce Prefix   |
       |  + Ephemeral X25519 Public Share                 |
       | <----------------------------------------------- |
       |                                                  |
       [ HKDF-SHA256 Derivation: Token + X25519 Secret ]  |
       [ ChaCha20-Poly1305 Frame Counter Starts at 1   ]  |

Every connection generates a fresh 8-byte nonce prefix and an ephemeral X25519 key pair. The directional session keys are derived using HKDF-SHA256 (hash-based key derivation function) over the pairing token and the scalar multiplication result. Every subsequent frame contains:

• 4-byte big-endian frame length
• 4-byte big-endian sequential counter
• ChaCha20-Poly1305 (high-speed authenticated stream cipher) ciphertext with authentication tag

The receiver strictly rejects any packet counter that does not match the exact sequential increment, neutralizing packet replay attacks instantly.

2. High-Frequency Mouse Sampling and Trackpad Acceleration

Legacy software KVMs forward mouse deltas as coarse single-pixel integer hops (dx, dy). When flicking an Apple Magic Trackpad or high-DPI mouse, this creates jittery, robotic cursor movement on the target display.

Beamer solves this in MSG_MOUSEMOVE by bundling a high-frequency micro-sample buffer:

# Extracted from core/protocol.py message parser
elif kind == MSG_MOUSEMOVE:
    if not _int(data.get("dx"), -MOVE_MAX, MOVE_MAX) or not _int(data.get("dy"), -MOVE_MAX, MOVE_MAX):
        return None
    read.update(dx=data["dx"], dy=data["dy"])
    if "samples" in data:
        samples = data["samples"]
        # Validates micro-sample timing arrays for smooth trackpad acceleration
        if sum(sample[0] for sample in samples) != data["dx"] or sum(sample[1] for sample in samples) != data["dy"]:
            return None
        read["samples"] = samples

The sender captures intermediate sub-pixel deltas during rapid sweeps, preserving natural macOS and Windows pointer acceleration curves across the network seam.

3. Atomic Clipboard Sync with Zip-Bomb Immunization

A common irritation with software KVMs is clipboard latency: you highlight code on your Mac, slide your cursor to your PC, press Ctrl+V, and paste old text because the clipboard synchronization packet trailed behind.

Beamer solves this through atomic pre-staging: the clipboard payload (MSG_CLIPBOARD) is sealed and transmitted ahead of the focus switch message. When your cursor enters the adjacent monitor, the clipboard is already decrypted and staged in local OS memory.

Furthermore, Beamer implements defenses against memory exhaustion. When synchronizing high-resolution screenshots from a Retina display (Apple high pixel density screen):

• Text is bounded to 256KB UTF-8.
• Images are capped at 8MB PNG payload.
• Before decompressing PNG bytes, Beamer inspects raw image headers via png_fits() to ensure pixel counts do not exceed PNG_MAX_PIXELS = 2^25 (33.5 million pixels, covering an 8K display). This prevents malicious decompression bombs from expanding into gigabytes of RAM.

Part 3: The Rough Edges (Where Software KVM Breaks)

While Beamer provides a remarkably clean user experience compared to legacy C++ tools, software-level input bridging across three disparate operating systems comes with sharp operational realities.

1. The macOS TCC Relaunch Trap

On macOS, capturing system-wide keystrokes and pointer coordinates requires granting two elevated permissions inside System Settings: Accessibility and Input Monitoring.

The fatal trap that confuses first-time users stems from macOS TCC (Transparency, Consent, and Control / Apple operating system security subsystem managing application permissions). When you toggle the Input Monitoring switch, macOS does not grant keystroke delivery to an active process. You must manually quit and relaunch Beamer. If you omit the relaunch, your cursor crosses screens effortlessly, but your keyboard remains dead on the destination machine.

2. Windows WinNAT Dynamic Port Hijacking

Older KVM tools like Synergy defaulted to port 51820. On Windows 10 and 11, developers frequently reported that their KVM worked on Monday, but failed on Tuesday morning after a system reboot.

The culprit is WinNAT (Windows Network Address Translation / internal networking driver used by WSL2 and Hyper-V). On system startup, WinNAT dynamically reserves arbitrary 100-port blocks within the dynamic port range (ports 49152 to 65535). If WinNAT claims port 51820, the KVM receiver fails to bind the socket, turning the bridge into a one-way street.

Beamer deliberately hardcoded DEFAULT_PORT = 24820 and PAIRING_PORT = 24821. By staying strictly below the 49152 threshold, Beamer guarantees that Windows never hijacks its listening sockets.

3. The Linux Wayland Security Barrier

If you run Linux on your secondary workstation, Wayland (modern Linux display server protocol replacing legacy X11) enforces strict security isolation. Unlike X11, Wayland explicitly forbids unprivileged applications from listening to global keystrokes or drawing overlay graphics across arbitrary windows.

As a result, running Beamer under Wayland imposes three mechanical compromises:

• Zero Edge Glow: Beamer cannot draw the visual edge-push illumination on a Wayland display.
• Input Capture Portal Dependency: Linux distributions must support xdg-desktop-portal with InputCapture portal interfaces (Ubuntu 24.04+ or Fedora 40+ GNOME/KDE 6).
• No Held Button Crossings: If you click and drag a file or window on Wayland before hitting the screen edge, Wayland prevents the cursor from transferring ownership.

Community Discourse on X (Twitter)

Developers testing modern cross-platform KVM alternatives on X highlighted the contrast between bloated proprietary suites and lightweight local tools:

Early adopters also flagged the real-world operational trade-offs when operating over busy wireless routers:

Part 4: Resolution & Decision Matrix

Beamer succeeds because it refuses to be an all-in-one remote desktop suite. It does not stream video, it does not route audio, and it does not sync files. It focuses on doing one job with mathematical rigor: delivering keyboard, mouse, and clipboard frames across local operating systems with zero noticeable latency.

Final Take

You do not need a three-hundred-dollar hardware switch or a bloated proprietary background daemon to control two computers from one keyboard. Run Beamer, punch in the six-digit pairing code, and let your mouse glide across operating system boundaries without your data ever touching the cloud.

Frequently Asked Questions (FAQ)

Does Beamer send my keystrokes to an external cloud server?

No. Beamer operates 100% peer-to-peer over your local area network (LAN). All input frames are encrypted end-to-end using ChaCha20-Poly1305 with ephemeral X25519 session keys. No accounts, telemetry, or external servers exist.

Why does my mouse cross over to the other screen, but keystrokes do not work on macOS?

This is caused by macOS TCC security permissions. After granting Accessibility and Input Monitoring permissions in macOS System Settings, you must completely quit and relaunch Beamer for macOS to deliver keyboard events.

Can I use Beamer over a VPN or different subnets?

Beamer is designed for machines sitting on the same local subnet. While you can manually enter an IP address, port, and token to route across subnets, corporate VPNs that block local subnet broadcast traffic will prevent automatic pairing.

How does Beamer prevent Windows port binding errors?

Beamer hardcodes default traffic to port 24820 and pairing to port 24821. Both ports sit safely below port 49152, completely avoiding the dynamic ephemeral port ranges that Windows WinNAT and WSL2 randomly claim during system boots. EOF