14 KiB
AGENTS.md — guide for AI coding agents
This file is written for large language model agents (Claude Code, Codex, Cursor, ...) that are asked to build, install, debug or develop uu-remote-linux. Read it fully before acting. Human documentation is in README.md (Chinese) and README.en.md.
1. What this project is
- An unofficial Linux host for NetEase UU Remote (网易 UU 远程). The official Mac / Windows / mobile clients connect to it and control the Linux desktop. There is no viewer/controller side here.
- One Rust binary,
uuremote-server(Cargo packageuu-remote-linux), plus small C engines inc_engine/compiled bybuild.rs. No Wine, no NetEase binaries. - The host registers with the UU cloud as a Windows PC (
x-param-plat=1) so the official clients accept it. - License GPL-3.0. Not affiliated with NetEase.
2. Ground rules (must follow)
- Privacy in logs. Never log keystrokes, terminal text, clipboard contents, file contents, passwords, tokens, QR login URLs or TURN credentials. Log sizes, counts, field numbers and booleans only. Existing code follows this; keep it that way in every new log line.
- The QR login URL is a credential. Show the QR only to the human who owns the account. Never paste the URL or a QR screenshot into chats, issues, logs or commits.
- Follow the official host behavior. Protocol behavior is copied from the official hosts (Mac
UURemoteServer, WindowsGameViewerServer.exe). Do not invent message shapes; when unsure, log the field numbers of what the viewer sends and derive behavior from evidence. - No NetEase assets. Do not add NetEase logos, icons, screenshots of their apps or copies of their binaries.
- No personal data in source. Nothing machine- or account-specific is compiled in; credentials come from
the config file / environment. The only built-in default is the public client signing key in
src/auth.rs. - Don't break other tools. The desktop, file-transfer, terminal and port-mapping tools each open their own peer connection; a new offer must never close other peers.
- Keep changes small and tested; match the surrounding code style (dense, comment only the non-obvious).
3. Build and test
Dependencies (Ubuntu/Debian):
sudo apt install build-essential pkg-config \
libx11-dev libxext-dev libxtst-dev libxfixes-dev libgtk-3-dev ffmpeg
# --features wayland: libwayland-dev libxkbcommon-dev wl-clipboard
# --features wayland,portal: + libglib2.0-dev libpipewire-0.3-dev
Rust stable via rustup. Commands:
cargo test # unit tests (macOS builds use C stubs, also fine for development)
cargo build --release # X11 host
cargo build --release --features wayland # + Hyprland/wlroots
cargo build --release --features wayland,portal # + GNOME/KDE Wayland via xdg-desktop-portal
build.rslinks X11/Xext/Xtst/Xfixes anddl(PAM is loaded at runtime withdlopen), and builds the GTK3 login window only whenpkg-config gtk+-3.0succeeds (UU_NO_GTK=1forces it off).- The portal feature panics in
build.rsif GIO/PipeWire development packages are missing. vendor/webrtc-dtlsis a patched copy of the upstream crate (MIT/Apache); keep it as a path dependency.- CI (
.github/workflows/ci.yml) runscargo test --lockedon ubuntu-22.04. Pushing av*tag runs.github/workflows/release.yml, which builds and publishes the x86_64 tarball; release notes come fromdocs/release-notes/<tag>.md.
4. Install on a user's machine (step by step)
-
Check the session:
echo $XDG_SESSION_TYPE $XDG_CURRENT_DESKTOP $DISPLAY $WAYLAND_DISPLAY. X11 → default build. Hyprland →--features wayland. GNOME/KDE on Wayland →--features wayland,portal(or advise the user to pick the "on Xorg" session at the login screen, which is the best-supported path). -
Install dependencies and build (section 3). Copy the binary:
install -Dm755 target/release/uuremote-server ~/.local/bin/uuremote-server. -
Login (needs the human). Run
uuremote-server logininside the graphical session. A GTK window shows a QR code; the user scans it with the UU Remote mobile app and confirms. Without a display useuuremote-server login --no-gui(terminal QR). Credentials are written to~/.config/uuremote/config.json(mode 0600). Do not read the token out of that file or print it. -
Create a systemd user unit (
~/.config/systemd/user/uuremote-native.service):[Unit] Description=UU Remote Linux host (unofficial) After=graphical-session.target [Service] Environment=RUST_LOG=info Environment=DISPLAY=:0 # GNOME on Xorg usually needs: Environment=XAUTHORITY=/run/user/<uid>/gdm/Xauthority ExecStart=%h/.local/bin/uuremote-server Restart=always RestartSec=5 [Install] WantedBy=default.targetFind the real display/Xauthority with
loginctl show-session <id> -p Display/ps -o args -C Xorg. -
systemctl --user daemon-reload && systemctl --user enable --now uuremote-native.service -
Verify:
journalctl --user -u uuremote-native.service -fmust showDevice status synchronized: ... availability=Some("ready"). If credentials are missing or expired the service opens the QR window on the desktop by itself (disable withUU_LOGIN_WINDOW=0). -
Ask the user to connect from the official client and check desktop, input, sound, file transfer, terminal.
Updating an installed binary: copy to a temp name and mv -f over the old one (a running binary cannot be
overwritten in place: "text file busy"), then restart the service. Restarting kills open viewer windows; the
viewer does not reconnect them automatically.
5. Runtime configuration
| Item | Meaning |
|---|---|
~/.config/uuremote/config.json |
user_id, device_id, client_id, system_id, machine_guid, token, csrf; optional sign_key, ffmpeg_root. $UU_CONFIG overrides the path |
~/.config/uuremote/host_settings.json |
persisted 安全 settings: auto_lock, keep_mute, mute_permanent |
UU_DESKTOP_BACKEND |
auto (default) / x11 / wayland / portal |
UU_VIDEO_ENCODER=cpu |
force libx264 instead of NVENC |
UU_FFMPEG_ROOT |
FFmpeg prefix (bin/ffmpeg, libs in lib/x86_64-linux-gnu) |
UU_AUDIO=0, UU_AUDIO_SOURCE |
disable sound / choose the Pulse source (default @DEFAULT_MONITOR@) |
UU_LOGIN_WINDOW=0 |
don't auto-open the login window |
Token has no expiry field; API code 1120 (HTTP 422) means invalid/expired → re-login. The config is re-read every 60 s.
6. Code map
| Path | Role |
|---|---|
src/main.rs |
entry, subcommands, room loop (one peer per ice_id), room renewal (deferred while connected) |
src/signaling.rs |
Engine.IO v4 / Socket.IO client; be-controlled binary attachment = ConnectOptions (field 1 capture_type) |
src/auth.rs, src/config.rs, src/login.rs, src/login_ui.rs |
signed REST client, config, device init + QR login, GTK window |
src/webrtc.rs |
peer connection, data channels, CONTROL dispatch, initialization messages |
src/video.rs, src/capture_setting.rs |
FFmpeg H.264 pipeline; viewer quality/fps/resolution settings |
src/audio.rs |
Pulse/PipeWire monitor → Opus audio track |
src/input.rs, src/input_mapping.rs |
input injection (X11 XTest / Wayland / portal), Windows VK → keysym |
src/cursor.rs |
pointer shape mirroring (X11) |
src/clipboard*.rs |
text clipboard bridge and protocol |
src/file_trans.rs |
FileTransferFtp RPC |
src/terminal.rs |
TERM frames + PTY sessions |
src/session_lock.rs, c_engine/pam_check.c |
lock state reporting, auto unlock via PAM + logind |
src/system_actions.rs, src/system_metrics.rs |
SimpleAction system commands, mute, auto-lock, SystemMetrics |
src/initialization.rs, src/control_protocol.rs, src/protocol.rs |
protobuf encoders/decoders for CONTROL |
src/session_ice.rs, src/network_diagnostics.rs |
cloud ICE servers, address-free path diagnostics |
src/desktop_backend.rs, src/wayland.rs, src/portal*.rs |
backend selection, Hyprland, GNOME/KDE portal |
c_engine/x11_engine.c, c_engine/clipboard.c |
X11 capture/input/selection |
c_engine/wayland_engine.c, c_engine/portal_engine.c |
Wayland and portal engines |
c_engine/login_window.c |
GTK3 login window |
Diagnostic subcommands: login [--no-gui], unlock-check (password on stdin, prints only accepted/rejected),
desktop-probe [new.png], desktop-video-probe, wayland-input-probe, clipboard-acceptance,
portal-acceptance, help. Unknown arguments exit with code 2. Builds up to v0.1.0 did not reject them and
started a second full host server instead, so check that a subcommand exists in the binary you run.
7. Protocol facts (verified against the official clients)
- Connection types (ConnectOptions.capture_type): 1 desktop, 5 file transfer, 8 terminal, 9 port mapping. Video is sent only for desktop connections (capture_type ≤ 2).
- CONTROL messages are protobuf
Message {1 seq, 2 timestamp, <which> payload}; input arrives as JSON (kbd_press,mouse_move_absolutewith normalized 0..1 floats, ...). - Echo: the viewer sends SimpleAction action 0 with its FeatureFlag; the host answers action 1 with args
{"seq":<request seq>}and its own FeatureFlag. The viewer only uses features the host declares:1 ff_capture_setting=4,2 ff_simple_action=2,3 ff_system_metrics=2,6 ff_file_transfer_ftp=2,8 ff_clipboard=3(when the clipboard bridge is ready). Do not declare versions you don't implement. - RPC = Message 21
RpcRequest {1 header{1 request_id}, <case>}, answered with Message 22RpcResponse {1 header (same id), <case>}. Cases used: 2 capture_setting, 3 fps, 4 video_quality, 6 resolution, 8 file transfer, 9 clipboard, 15 send_video_track, 16–20 plugins, 21 virtual audio policy, 28/29 terminal. - CaptureSettingRequest: field 1 is an fps option index (1=30, 2=60, 3=90); the real frame rate is
field 18
fpsCount. Field 2 quality: 1 Fast, 2 General (高清 2M), 3 HD (超清 8M), 4 Bluray (原画 20M), 5 Auto, 6 Custom. Resolution: 16/17 pixel size or 5/6, 10 resolution_type (3 = follow remote). ReplyRpcResponse{2 CaptureSettingResponse{}}(no errors = applied) and send Message 25 CaptureSettingSync. - SystemMetrics (Message 13): GeneralMetric
2 system_sound_supportis an enum, 2 = supported (1 = not supported); SettingMetric 1 keep_mute, 2 mute_permanent, 3 auto_lock, 5 file_transfer_save_location, 8/9/10 permission states (2 = allow). - Security menu: 静音运行 on → SimpleAction 14 + 18, off → 16. 远程结束后自动锁屏 → SimpleAction 19 with
value(field 5) 2 = on, 1 = off. The viewer sends these only when toggled, so the host persists them. - Auto unlock: host reports
SystemStateChange{1 SecureDesktopState{1 is_locked, 5 is_support_auto_logon}}; the viewer (after the user enables 自动解锁被控端) sends SimpleAction 15 with args{"key": password}; failure → Message 12ReportError{2: -5}. - File transfer: the viewer sends RPCs on CONTROL but receives only on FILE_DATA_CHANNEL, so all replies go
out on FILE. With
ff_file_transfer_ftp=2directory listings are zlib-compressed protobuf.remove_diris sent for every delete and must be answered with response case 6result{id, file_error}, notoperation_result. Host root is shown as ":/" (此电脑); home is "~/". - Terminal: BINARY channel, RPC 28 check_env → 24; frames
"TERM", version 1, type (enum+1), 2 flag bytes, session u32 LE, length u32 LE, payload; JSON{cols,rows,shell,option}. - Cursor shape = Message 15 SystemStateChange field 2. Audio: the viewer always offers an Opus m-line.
- Login API:
/api/v1/device/windows/init→ device_id;/qrcode/gen/login; long-poll/qrcode/login/status(1 wait, 2 scanned, 4 confirmed);/login/by_qrcode→ user token. QR expires after ~5 min with HTTP 400 code 1190 (not fatal: generate a new one).
8. Known pitfalls
- webrtc-rs
Sample.durationsets the gap to the next frame. FFmpeg 6.1 rejects-rtogether with-fps_mode vfr. - All-intra 60 fps saturates Wi-Fi; keep GOP ≈ 0.5 s. A bitrate cap alone does not change quality on a static desktop, so presets also change the CQ level.
- X11 capture on a GPU saturated by CUDA work starves; prefer the iGPU for the desktop when available.
- Remote keys repeat at high RTT because key-up arrives after the X autorepeat delay. XTEST repeats through the master keyboard; the engine disables global autorepeat only while a remote key is held.
- Interactive shells ignore SIGTERM: the server HUPs/KILLs PTY sessions on shutdown.
- GTK windows stop repainting while GNOME is locked or the monitor is off; test UI on Xvfb or after unlock.
- logind
unlock-sessionby the session owner clears the GNOME shield in ~3 s. - GNOME closes the portal session on lock; capture/input must share one portal session and be rebuilt after unlock. Portal input/clipboard permissions are persisted per desktop (0600 file); a revoked permission asks again.
9. Debugging checklist
- Connection:
Offer for connection: capture_type=,PeerConnection State changed,ICE path: ... route=. - Video:
Desktop encoder: ... fps= cq= maxrate=,Desktop latest-frame stats,Video feedback totals. - Viewer requests:
CONTROL message: fields=[..] simple_action=..(numbers only),Capture setting request,SimpleAction N (...) received. - Features:
File transfer ...,Terminal frame,Native desktop clipboard text received: bytes=,Desktop audio started,Auto unlock result,Auto lock after remote session. - When the viewer "does nothing" after a menu click, first check whether any message arrived; usually the host did not declare the matching FeatureFlag/SystemMetrics capability.
10. Contributing
- Run
cargo test(and the feature builds you touched) before committing; keep commits focused. - New protocol behavior: cite the evidence (observed field numbers, official log strings) in a comment.
- Update README.md / README.en.md when user-visible features or limitations change, and add
docs/release-notes/<tag>.mdbefore tagging a release.