hyprCRD

Project Name: hyprCRD

Overview
hyprCRD serves as a native host solution for Google Chrome Remote Desktop, specifically optimized for the Hyprland Wayland compositor. This project facilitates seamless streaming of the active hardware-accelerated desktop session directly over WebRTC. Unlike traditional methods that rely on virtual X11 framebuffers (Xvfb), hyprCRD allows direct access to the desktop environment, enhancing performance and user experience.

Key Features

• Integration with Google WebRTC: Utilizes unmodified Google WebRTC binaries to maintain compatibility with standard clients across various platforms, including Android, iOS, and web browsers.
• Native PipeWire Support: Employs PipeWire to enable efficient zero-copy GPU capture, with a software fallback for enhanced flexibility.
• Stream Renegotiation Handling: Implements a lightweight preload shim that safeguards against invalid dynamic format renegotiation requests from variable-client environments, ensuring uninterrupted streaming.
• Input Emulation: Leverages a C++20 D-Bus portal service (hyprcrd-portal) for effective emulation of input protocols using libei and associated libraries, enhancing the remote user experience.
• Keymap Synthesis: Accurately compiles and manages the compositor's active XKB keymap in shared memory, effectively supporting modified keys and international keyboard layouts.
• Security and Privilege Management: Designed to run without elevated permissions, adhering to best practices by using standard user session contexts without the need for setuid binaries.

Architecture

The architecture of hyprCRD integrates multiple services to facilitate a streamlined connection between client devices and the hyprland desktop session. Below is a visual representation of the system architecture:

flowchart TD
    Client["Client Device (Android / iOS / Web)"] <-->|"WebRTC / Google FTL Signaling"| CRDHost["Google Remoting Host (chrome-remote-desktop-host)"]

    subgraph hyprCRD ["hyprCRD User Session"]
        CRDHost <-->|"D-Bus: org.freedesktop.impl.portal.RemoteDesktop"| Portal["hyprcrd-portal (C++20 Bridge)"]
        CRDHost -->|"Preload Interceptor"| Shim["pam_shim.so (C99 Hook)"]

        Shim -->|"Resolves cursor_mode & stream renegotiations"| PipeWire["PipeWire Media Server"]
        Portal -->|"EIS Protocol (libei/libeis)"| InputServer["Virtual Input Controller"]
        InputServer -->|"zwlr_virtual_pointer_v1"| HyprlandPointer["Hyprland Virtual Pointer"]
        InputServer -->|"zwp_virtual_keyboard_v1 + XKB"| HyprlandKeyboard["Hyprland Virtual Keyboard"]
    end

    PipeWire <-->|"DMA-BUF / SHM Capture"| XDPH["xdg-desktop-portal-hyprland"]
    XDPH <-->|"Wayland Screencopy"| HyprlandCompositor["Hyprland Compositor (Physical Output)"]

Feature Comparison

The table below highlights the capabilities of hyprCRD compared to legacy systems and upstream Wayland implementations:

Detailed technical information can be found in ARCHITECTURE.md.

Usage

To utilize hyprCRD effectively, the following commands can be executed:

Verify Environment Configuration

hyprcrd doctor

Host Registration

hyprcrd enroll "<COMMAND_STRING>"

Manage Service

hyprcrd start   # Start the background daemon
hyprcrd start -f   # Run in foreground for debugging
hyprcrd status   # Check runtime status
hyprcrd stop   # Stop daemon

Example runtime status output:

[hyprCRD Status]
  Daemon:         ACTIVE (PID: 3715)
  Portal Bridge:  ONLINE (PID: 1572)
  Enrolled Host:  workstation (ID: 855a3928-3500-4401-8b45-1a3206d55740)

Testing and Verification

To ensure functionality and stability of the service, testing can be performed using:

make test

This test suite covers multiple aspects, including PAM preload mechanisms, portal logic, and integration with the Wayland compositor.

Security Policy

hyprCRD operates under an unprivileged security model, ensuring that all operations are conducted within the user's standard session context. For specifics on vulnerability reporting and best security practices, refer to SECURITY.md.

For contributions, development guidelines, and more in-depth information regarding testing, see CONTRIBUTING.md.

This project represents a significant advancement in the seamless usage of Google Chrome Remote Desktop within the rapidly evolving environment of Wayland compositors, specifically catering to the Hyprland ecosystem.