sqlpxc/airhand

选用指南

AI 根据 README 整理 · 2026/11/1 13:01:48

适用场景

适用于需要低延迟、低带宽远程控制的场景，如远程办公、多电脑管理、观看视频等。

查看 README 依据

- **Low latency, low bandwidth**: hardware **AV1 / HEVC / H.264** encoding, no frames when the screen is still, adaptive bitrate, the cursor moves locally with no lag - **Audio**: the host's system sound is streamed to the controller, with optional A/V sync for watching video - **Practical tools**: two-way clipboard sync, typing the clipboard as keystrokes, system shortcuts (Win, Alt+Tab, Ctrl+Shift+Esc…), multiple monitors, fullscreen with keyboard lock - **Zero files**: no config file, nothing is left on disk (see [below](#zero-files))

Audio goes through a jitter buffer while video is shown as soon as it arrives, so by default audio lags video slightly: about **70 ms** in our measurements (same machine, local relay, 4K output at 1080p; 49–78 ms per run). That's barely noticeable while working, but may be when watching video. With **A/V sync** turned on (speaker menu in the toolbar):

目标用户

面向需要远程控制 Windows 或 Linux（X11）桌面的用户，包括个人和开发者。

查看 README 依据

<p align="center"><img src="assets/icon.svg" width="96" alt="Airhand"></p> <h1 align="center">Airhand</h1> <p align="center">High-performance remote desktop over QUIC · Rust + Tauri + React</p> <p align="center"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p> --- Airhand is a single program that is both the **host** (the computer being controlled) and the **controller** (the computer you control it from). It runs on **Windows** and **Linux** (X11 desktops). A small relay server, deployed with one Docker Compose command, handles signaling and forwards traffic.

使用方式

通过图形界面使用，主机端默认启动后仅显示托盘图标，控制端通过输入控制码连接。

查看 README 依据

> **Status:** under active development. The protocol still changes between versions, so the clients and the server must be built from the same version (a mismatch is detected and reported, see [Protocol versions](#protocol-versions)). ## Features - **Host by default**: after launch there is only a tray icon, no window, and no WebView is started - **Controller console**: control **several computers at once**, switch between them, or watch them all in a multi-screen overview

3. **Run it on both computers.** On the remote one, right-click the tray icon to see its 6-digit **control code**. On yours, choose **Switch to controller** in the tray menu and enter the code. ## Usage ### Host (default) Double-click to run. A tray icon appears in the bottom-right corner (on Linux, in the top bar / panel status area). Grey means not connected to the server, coloured means connected. The right-click menu contains: - Current mode and server status - The **control code** and "Copy control code" - Who is controlling this computer right now, and **Disconnect all controllers**

部署要求

需要部署一个中继服务器（Docker Compose），客户端构建需要 Rust、Node.js 20+ 和 CMake。Windows 需要 Windows 10/11，Linux 需要 Tauri 依赖和 GStreamer 插件。

查看 README 依据

- **Secure by default**: TLS 1.3 with certificate pinning, brute-force protection for control codes - **English and Simplified Chinese**: follows the system language, switchable at any time ## Contents - [Quick start](#quick-start) - [Usage](#usage) - [Server configuration](#server-configuration) - [Building the client](#building-the-client) - [How it works](#how-it-works) - [Security](#security) - [Known limitations](#known-limitations) - [Development](#development) ## Quick start 1. **Deploy the server** on a machine both computers can reach (only **UDP 4433** needs to be open):

| `AIRHAND_LISTEN` | `0.0.0.0:4433` | Listen address (UDP) | | `AIRHAND_CERT` / `AIRHAND_KEY` | `/data/cert.pem` / `/data/key.pem` | Certificate paths; generated automatically if missing | | `AIRHAND_CERT_NAMES` | `airhand,localhost` | SANs written into an auto-generated certificate | | `AIRHAND_MAX_SESSIONS` | `4` | Max simultaneous controllers per host | | `RUST_LOG` | `info` | Log level | The image is based on distroless, runs as a non-root user, and is about 28 MB. ## Building the client Requirements: Rust (stable), Node.js 20+, CMake (to build libopus).

- **Windows**: Windows 10/11 (WebView2 ships with the OS) - **Linux**: Tauri's dependencies, the PulseAudio development files and the GStreamer plugins the console uses to decode video. On Debian / Ubuntu: ```bash sudo apt install build-essential cmake pkg-config libssl-dev libwebkit2gtk-4.1-dev \ libayatana-appindicator3-dev librsvg2-dev libxdo-dev libpulse-dev \ gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav ```

已知限制

主机仅支持 Windows 和 Linux X11 桌面，Wayland 下仅支持 XWayland 应用；Linux 主机仅支持 OpenH264 软件编码；剪贴板仅同步文本；音频仅从主机流向控制端。

查看 README 依据

- The host supports Windows and Linux **X11** desktops. Under Wayland only X11 (XWayland) applications can be seen and controlled; native Wayland windows are black and the controller suggests logging in with an X11 (Xorg) session. Full Wayland support needs xdg-desktop-portal screen sharing (the local user has to confirm each time) and isn't implemented - The Linux host only has OpenH264 software encoding (no VA-API / NVENC yet); when AV1 / HEVC is selected it uses H.264

- The clipboard syncs text only, not files - Audio flows from host to controller only; the controller's microphone isn't forwarded. Audio is captured after the volume control, so a muted host sends silence ## Development ### Tests ```bash # repository root: protocol + server cargo test # client/: UI (jitter buffer and A/V sync simulations, H.264 conversion, UI strings) npm test # client/src-tauri/: client Rust (encoders incl. hardware probing, Opus packing, format conversion…) cargo test --lib