BeamDesk

Turn another Mac into a real, independent extended display.

GitHub · Project context · Architecture · Testing

BeamDesk is a native macOS sender/receiver pair for using a second Mac as an extended desktop over a local IP connection. The sender creates a WindowServer-recognized virtual display; macOS can place windows on it; the receiver decodes and renders that desktop fullscreen.

This is an early direct-distribution build focused on Apple hardware, low latency, and an honest engineering feedback loop. It is not screen mirroring, remote desktop control, or a video streaming service.

What works today

• Independent virtual display with a 2560×1440 logical desktop and a native 5120×2880 HiDPI backing surface.
• Hardware HEVC capture, encode, decode, and Metal presentation.
• Sender-side receiver discovery, explicit pairing, trusted identities, and Thunderbolt Bridge/Wi-Fi endpoint selection.
• Optional shared keyboard and mouse input between the two Macs.
• Native mode (up to 5K) and Smooth mode (up to 4K), selectable per receiver.
• Bounded queues, newest-frame preference, reconnect handling, and live pipeline telemetry.
• English and Simplified Chinese localization.

The independent-display path has been exercised on a physical 2015 Retina 5K iMac. Native 5K motion runs currently reach roughly 55–57 fps on the verified Thunderbolt path; stable 60 fps and physical glass-to-glass latency are not claimed. Wi-Fi performance is materially more variable. See the dated evidence in TESTING.md before treating any number as a benchmark.

How it works

MacBook / Sender                                      Second Mac / Receiver
┌────────────────────────┐                            ┌──────────────────────┐
│ WindowServer virtual   │                            │ Discovery + pairing  │
│ extended display       │                            │                      │
│          ↓             │                            │ HEVC hardware decode │
│ ScreenCaptureKit      │   local IP / Thunderbolt   │          ↓           │
│          ↓             │ ────────────────────────▶ │ Metal fullscreen view │
│ VideoToolbox + bounded │                            │                      │
│ low-latency transport  │                            │ Optional shared input│
└────────────────────────┘                            └──────────────────────┘

The transport is IP-based. A connection is described as Thunderbolt Bridge, Ethernet, Wi-Fi, or another interface only after the active local and peer endpoints identify that path. An SSH alias alone is not treated as proof of Thunderbolt transport.

Hardware and software

Role	Verified target
Sender	Apple-silicon MacBook, current macOS development SDK
Receiver	2015 Retina 5K iMac17,1, Intel, macOS 12.7.6
Display path	macOS virtual display → ScreenCaptureKit → VideoToolbox → Metal
Network	Thunderbolt Bridge first; Wi-Fi and Ethernet are supported paths

The package remains Swift 5.7-compatible because the Intel receiver is a hard compatibility target. The app uses AppKit, SwiftUI, Metal, Network.framework, ScreenCaptureKit, and VideoToolbox. No package-manager dependencies are required.

Quick start

Run these commands on the sender Mac from a checkout of this repository:

make bootstrap
make start

make start builds the sender and receiver, deploys the receiver to the configured imac-thunderbolt host, and launches both apps. Follow DEVELOPMENT_ENVIRONMENT.md first if you are setting up a new machine or installing a new signed build.

On first launch:

1. Grant Projector/BeamDesk Sender Screen Recording access in macOS Settings.
2. Grant the requested Accessibility and Input Monitoring access if shared keyboard/mouse input is enabled.
3. Pair the two Macs using the matching code shown by both apps.
4. Enable the receiver from the sender's Control Center.
5. Arrange the new display in System Settings → Displays, then move windows onto it.

Quit the sender to remove its virtual display. The receiver can remain running and wait for a trusted sender.

Development

make build          # compile the Swift package
make test           # run XCTest coverage
make check          # build and test
make probe          # inspect local VideoToolbox capabilities
make remote-test    # compile and self-test against the Intel iMac
make apps           # build the BeamDesk app bundles

For the complete deployment runbook, compatibility notes, diagnostic commands, and hardware-test expectations, read DEVELOPMENT.md. Changes involving capture, codecs, transport, Metal, virtual displays, or display modes require the relevant physical hardware check; unit tests alone are not enough.

Project map

• Product direction — user outcome and product principles.
• Project context — verified hardware, constraints, and current targets.
• Architecture — pipeline boundaries and decisions.
• Development environment — signing, installation, permissions, and receiver setup.
• Testing record — dated measurements and what they do not prove.
• Architecture decisions — protocol and implementation history.
• Contributing — focused changes, tests, and ADR expectations.
• Third-party notices — referenced implementation licenses.

Naming note

BeamDesk is the product and app brand. The Swift package, executable targets, bundle identifiers, and some historical source symbols still use Projector for compatibility with existing builds and permissions. This repository is deliberately not a wholesale rename.

Current limitations

• Stable 60 fps is not established for real desktop motion.
• Physical glass-to-glass latency is not currently measured.
• Native 5K and Smooth 4K are user-selectable; the best mode depends on the receiver and network path.
• The Mac App Store is not a target because the virtual display uses private CoreGraphics declarations isolated on the sender side.
• Hardware validation is centered on the verified MacBook + 2015 iMac pair.

BeamDesk is built for people who want the second Mac to feel like a display, not like a remote-computing session.