LiveDesk Client

Run a direct LiveDesk remote client from a controlled computer.

npx -y livedesk client
npx -y livedesk 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 opens Google sign-in, waits for the active LiveDesk Hub published by the same account, and connects locally. If the Hub is not ready yet, the client keeps checking every 5 seconds instead of exiting. 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.

On Windows, check Start with Windows on the connection page to reconnect this client automatically after reboot. The startup entry reuses the saved Google session and only opens the connection page again if sign-in is needed.

On the Hub computer, open the LiveDesk dashboard and sign in first. The dashboard keeps its local Hub address and private pair token refreshed in the LiveDesk Supabase registry for the signed-in account.

Supabase Auth must allow the CLI callback URL:

http://127.0.0.1:5198/callback

If you use a custom port, run npx -y livedesk 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 Windows system-audio loopback playback. macOS control requires Accessibility permission for the terminal app that started LiveDesk; screen streaming requires Screen Recording permission. LiveDesk opens the matching System Settings page only when that permission is first needed. When file transfer is enabled by the Hub, received files are saved to Desktop/LiveDeskFiles 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 for AI assist or 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. 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 livedesk client 3
npx -y livedesk client --no-thumbnail
npx -y livedesk client --no-live
npx -y livedesk client --no-audio
npx -y livedesk client --files-dir "D:\LiveDeskFiles"
npx -y livedesk client --engine node
npx -y livedesk client --engine fast --trace-frames
npx -y livedesk client --auth-port 5200
npx -y livedesk 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 hardware H.264 path. Windows tries Media Foundation/NVENC/QSV/AMF, macOS prefers ScreenCaptureKit plus VideoToolbox, and Linux tries NVENC/VAAPI/QSV. macOS emits one startup key frame and then an approximately one-second 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.