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 (stable), 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 или новее и Linux с рабочими столами на X11. Wayland не упоминается.
Можно ли запустить ретранслятор на VPS?Да. Ретранслятор разворачивается через Docker Compose на любой машине, до которой могут достучаться оба компьютера. Нужно открыть только входящий UDP 4433.
Соединение зашифровано и защищено?Да. Трафик идёт по TLS 1.3 с закреплением сертификата, а коды управления защищены от перебора.
Можно ли управлять компьютером из браузера без установки чего-либо?Да. Контроллер может работать как веб-консоль в Docker Compose, и тогда вы открываете один порт в браузере. На компьютере, с которого вы управляете, ничего устанавливать не нужно, однако управляемые компьютеры всё равно должны запускать клиент Airhand.
Что происходит на управляемом компьютере?После запуска показывается только значок в трее, без окна и без WebView. После обрыва сети клиент переподключается автоматически и сохраняет прежний код управления, даже после перезапуска сервера.
Что можно делать после подключения?Можно управлять сразу несколькими компьютерами, пользоваться обзором нескольких экранов, синхронизировать буфер обмена в обе стороны или вводить его как нажатия клавиш, передавать системный звук хоста с необязательной синхронизацией A/V и использовать адаптивный битрейт для низкой задержки.
Какие есть похожие проекты?rustdesk-server, xpra, nyaterm, Cap, numa, omnyssh, Piik, buzz
Автор
sqlpxc
Размер
3.4 MB
Звёзды
1.4K
Возраст
18 д
Коммиты · 90 дней