VuvoDesk Client

For normal users, run the unified VuvoDesk application:

npx -y --prefer-online livedesk@latest

The direct Client form remains available for compatibility and diagnostics.

npx -y --prefer-online livedesk@latest client
npx -y --prefer-online livedesk@latest client 3

@livedesk/client is the internal direct package and remains available for advanced diagnostics. The public command above keeps Hub and client versions aligned.

The default flow lets the local Client runtime own Google authorization, callback exchange, and saved authentication as one path. The browser only shows progress; it does not maintain a second session that must be transferred back to the Client. VuvoDesk then waits for the active Hub published by the same account and connects locally. If the Hub is not ready yet, the client waits for a Hub-online event and polls the registry at most every six seconds as a fallback. Missing a wake event can never leave a Client asleep for minutes. If a connected Hub is replaced, the launcher also leaves the stale endpoint and discovers the newly published Hub without another Google login. Omit the number for first-available placement, or pass 1 to 999 to pin this machine to a screen wall slot.

Installed VuvoDesk desktop apps start automatically after sign-in on Windows, macOS, and Linux by default. The startup entry reuses the saved Google session, reconnects quietly, and only opens the connection page again if sign-in or first-run role setup is needed. Turn this off in Settings > Desktop app.

On the Hub computer, open the VuvoDesk dashboard, sign in, and run Sync Server once. The dashboard transfers the signed-in session to the local Hub; the Hub process then keeps its own local address and private pair token refreshed in the VuvoDesk Supabase registry. The dashboard can be closed after that while the Hub remains running.

Supabase Auth must allow the CLI callback URL:

http://127.0.0.1:5179/callback

If you use a custom port, run npx -y --prefer-online livedesk@latest client --auth-port 5200 and add the matching callback URL to Supabase Auth redirect URLs.

The client registers the device, sends status heartbeats, can return Hub-requested thumbnails, can stream a focused view-only live screen, and can receive safe task-only instructions. The C# RemoteFast engine also supports keyboard/mouse control on Windows, macOS, and Linux/X11, file transfer, and system-audio playback from Windows, macOS, and Linux. Linux captures the default output through PipeWire pw-record or PulseAudio parec. macOS control requires Accessibility permission for the terminal app that started VuvoDesk; screen streaming and system-audio capture require Screen Recording permission. VuvoDesk checks these permissions without opening repeated system dialogs and prints the matching System Settings path when access is missing; after granting access, restart the client. When file transfer is enabled by the Hub, received files are saved to Desktop/VuvoDeskFiles unless the Hub sets another destination folder.

By default, the launcher uses the packaged C# RemoteFast engine when supported. It falls back to the Node engine only when a compatible RemoteFast runtime is unavailable. Windows, macOS, and Linux all try RemoteFast first so the Hub can request the Mode 3 hardware video path when it is available. RemoteFast is shipped as a platform-specific self-contained .NET executable, so client computers do not need a separate .NET installation. The launcher also includes a prebuilt ffmpeg executable through @ffmpeg-installer/ffmpeg and passes it to RemoteFast automatically. Set LIVEDESK_FFMPEG to override that path. If you need LGPL-only distribution, point LIVEDESK_FFMPEG at a verified LGPL ffmpeg build before shipping.

Useful flags:

npx -y --prefer-online livedesk@latest client 3
npx -y --prefer-online livedesk@latest client --no-thumbnail
npx -y --prefer-online livedesk@latest client --no-live
npx -y --prefer-online livedesk@latest client --no-audio
npx -y --prefer-online livedesk@latest client --files-dir "D:\VuvoDeskFiles"
npx -y --prefer-online livedesk@latest client --engine node
npx -y --prefer-online livedesk@latest client --engine fast --trace-frames
npx -y --prefer-online livedesk@latest client --auth-port 5200
npx -y --prefer-online livedesk@latest client --logout

Frame pipeline roadmap:

• Mode 1: mode1-jpeg - current test path using screen capture, resize, and JPEG binary frames.
• Mode 2: mode2-lzo - cross-platform wall path using independent RGB565LE frames capped at 320x180 and compressed as LZO1X blocks. The wall defaults to 8 fps. macOS and Linux keep one persistent local capture helper per client process. Legacy mode2-lz4 settings migrate to this mode.
• Mode 3: mode3-h264-hw - OS-specific H.264 path. Windows tries Media Foundation/NVENC/QSV/AMF, macOS prefers ScreenCaptureKit plus VideoToolbox, and Linux tries NVENC/VAAPI/QSV before falling back to the bundled ffmpeg libx264 encoder. Linux users do not need to install ffmpeg separately when starting VuvoDesk through the published npm package. macOS emits one startup key frame and then an approximately half-second recovery GOP. The launcher uses bundled ffmpeg for fallback paths unless LIVEDESK_FFMPEG points to a custom binary. On macOS, set LIVEDESK_FFMPEG_AVFOUNDATION_INPUT only when the ScreenCaptureKit helper is unavailable and the AVFoundation fallback input is not 1:none.

Legacy mode names such as remote-fast and remote-quality are treated as Mode 1 aliases.