airhand README

项目的 README,来自 github.com/sqlpxc/airhand。合并为一个 markdown 文件:README.md。

Airhand

Airhand

High-performance, low-latency remote desktop
QUIC transport · hardware encoding and decoding · up to 120 fps
Windows · macOS · Linux · Android · browser

English · 简体中文


Airhand is a high-performance, low-latency remote desktop: the screen is encoded on the GPU (AV1 / HEVC / H.264) at up to 120 fps and sent over QUIC; when the network slows down it skips to the latest frame instead of letting lag pile up; and the mouse pointer is drawn locally, so it moves without delay.

The same program is both the host (the device being controlled) and the controller (the device you control it from). The two sides meet through a relay server that you deploy yourself. It's small, and Docker Compose deploys it with one command. Enter the other side's 6-digit control code to connect.

[!NOTE] Work in progress (0.2.3). Since protocol v9, client ⇄ server and host ⇄ controller each support a range of versions, new features are negotiated with capability bits and unknown messages are skipped, so later versions can be mixed; versions before v9 are incompatible, which is detected and reported (see Protocol versions).

Performance

Every stage from capture to display is built for low latency:

See How it works → Video for details.

Features

Platforms

Platform Host Controller Notes
Windows 10 / 11 ✅ ✅ Installed; the host runs as a system service
macOS 13+ ✅ ✅ The host needs the Screen & System Audio Recording and Accessibility permissions
Linux ✅ ✅ The host supports X11 desktops only, with software encoding for now
Android 7+ phones / tablets ✅ ✅ Can only be watched until the accessibility service is turned on; the controller connects to one device at a time
Android TV / Google TV — View only Operated entirely with the remote
Browser (web console) — ✅ Chrome / Edge, Safari 16.4+, Firefox 130+

See Known limitations for platform-specific caveats.

How it works

flowchart LR
    host["Host<br>Windows / macOS / Linux / Android"]
    relay["Relay server<br>airhand-server (Docker)"]
    ctrl["Controller<br>desktop console / web console / Android"]
    host <-->|"QUIC · UDP 4433"| relay
    relay <-->|"QUIC · UDP 4433"| ctrl
    host -. "direct (when possible)" .- ctrl

The host connects to the relay server and gets a 6-digit control code; the controller uses that code to find it. The server only registers codes, pairs sessions and forwards bytes; sessions are end-to-end encrypted, so it can't see their content. Both the host and the controller connect out to the server, so neither needs an open port or a public IP. Once a session starts, the two ends also try to punch a direct path; when that works, the video no longer goes through the server (otherwise it stays on the relay). See How it works for details.

Quick start

You need:

1. Deploy the relay server

git clone https://github.com/sqlpxc/airhand.git
cd airhand
docker compose up -d
docker compose logs airhand | grep fingerprint   # note the certificate's SHA-256 fingerprint

The certificate and the control-code database live in data/. Keep that directory: with a new certificate, clients you've already built can no longer connect. Server settings are in Deployment.

2. Build the client

Compile in the server address and the fingerprint from step 1.

Windows (PowerShell):

cd client
npm install
$env:AIRHAND_SERVER    = "relay.example.com:4433"
$env:AIRHAND_SERVER_FP = "<fingerprint from step 1>"
npm run tauri build

macOS / Linux:

cd client
npm install
export AIRHAND_SERVER=relay.example.com:4433
export AIRHAND_SERVER_FP=<fingerprint from step 1>
npm run tauri build

The packages are under client/src-tauri/target/release/bundle/:

System Package
Windows nsis/Airhand_<version>_x64-setup.exe
macOS macos/Airhand.app, dmg/Airhand_<version>_<arch>.dmg
Linux deb/Airhand_<version>_amd64.deb

The server address and fingerprint can also be changed later in config.toml. For the Android APK, see Building → Android.

3. Connect

  1. Install Airhand on both computers (on Windows run the installer, which needs administrator rights; on macOS grant the permissions it asks for the first time)
  2. On the computer to be controlled, right-click the tray icon (on macOS, click the menu bar icon) to see its 6-digit control code
  3. On your computer, choose Open console from the tray menu (Switch to controller on macOS / Linux) and enter the code. The first time you connect to that computer, also enter the 6-digit pairing code from its tray menu; after that it isn't needed

The full guide is in Usage.

Without installing a client: the web console

Start the web console on any machine with Docker and use it from a browser:

cd web
AIRHAND_SERVER=relay.example.com:4433 AIRHAND_SERVER_FP=<fingerprint> docker compose up -d

Open http://localhost:8080 on that machine, or https://<its address>:8080 from other computers. For the access password, the HTTPS certificate and reverse proxies, see Deployment → Web console.

Documentation

Document Contents
Usage Host, Windows installation, configuration file, uninstalling, console, quality, language
Deployment Relay server settings, web console, reverse proxies
Android Controlling from a phone, sharing the phone, gestures, TVs
Building Per-platform requirements and packages, signing, APK
How it works Architecture, source layout, Windows service, video and audio pipelines, A/V sync, files on disk
Security Encryption and pinning, brute-force protection, control codes and resume tokens
Known limitations Known issues by platform
Development Tests, debugging tools, project conventions

Security notes

See Security for details.

Contributing

Directory Contents
crates/ The protocol (airhand-proto) and the client-to-relay link (airhand-link)
server/ Relay server
web/ Web console service
client/ Desktop client: Tauri (Rust) + React UI, which the web console uses too
android/ Android app (Kotlin + Jetpack Compose) and its Rust core

How to run the tests, the debugging tools and the project conventions (protocol versions, UI strings…) are in Development.

License

MIT

airhand (sqlpxc/airhand)

正在搜索数据库…

1.4K ·GitHub
这是什么?远程桌面软件。同一个程序既可以作为被控端(被控制的电脑),也可以作为控制端(用来控制对方的电脑),两者通过一个小型中继服务器,基于 QUIC 协议连接。
是单个应用还是服务器?两者都是。你需要在每台电脑上运行桌面客户端,并使用 Docker Compose 部署一个中继服务器,由它负责信令交换,并在两端之间转发流量。
怎么运行起来?先在两台电脑都能访问的机器上,用 Docker Compose 部署中继服务器。然后构建客户端,并把服务器地址和证书指纹编译进去,在两台电脑上分别运行,再输入远程端显示的 6 位控制码。
构建客户端需要什么?Rust(稳定版)、Node.js 20+ 和 CMake。Windows 需要 Windows 10/11;macOS 需要 13 及以上版本,并安装 Xcode Command Line Tools;Linux 需要 Tauri 的依赖项、PulseAudio 开发文件以及 GStreamer 插件。
有哪些限制?项目仍在积极开发中,协议会随版本变化,因此服务器和所有客户端必须使用同一版本构建。在原版 GNOME 上,Linux 托盘图标需要 AppIndicator 扩展;macOS 则需要“屏幕录制”和“辅助功能”权限。
支持哪些操作系统?Windows、macOS 13 及以上版本,以及使用 X11 桌面的 Linux。文档中未提及 Wayland。
能在 VPS 上运行中继吗?可以。中继是一个 Docker Compose 部署,可以放在两台电脑都能访问的任意机器上,只需开放入站 UDP 4433 端口。
连接是否加密,是否有安全保护?是的。流量使用 TLS 1.3 并进行证书固定,控制码也有防暴力破解保护。
无需安装任何软件,能否通过浏览器控制电脑?可以。控制端可以以 Web 控制台的形式在 Docker Compose 中运行,你只需在浏览器中打开一个端口即可。控制端所在的电脑无需安装任何软件,但被控制的电脑仍需运行 Airhand 客户端。
被控制的电脑上会发生什么?启动后只显示一个托盘图标,没有窗口,也不使用 WebView。网络断开后会自动重连,即使服务器重启,也会保留原来的控制码。
连接后可以做什么?可以同时控制多台电脑,并使用多屏总览;双向同步剪贴板,或将其以按键方式输入;串流被控端的系统声音,可选择开启音画同步;还能使用自适应码率来降低延迟。
有哪些类似的项目?rustdesk-server, xpra, nyaterm, Cap, numa, omnyssh, Piik, buzz
作者
sqlpxc
大小
3.4 MB
星标
1.4K
时长
18天
提交 · 90 天