VuvoDesk

livedesk is a thin cross-platform launcher. npm installs only the matching RemoteFast package for the current operating system and CPU, so Windows, macOS, and Linux native binaries are no longer downloaded together.

One-command VuvoDesk application. The same launcher resolves this computer's Hub or Client role. A Client starts one managed Agent. A Hub starts the Hub server plus one headless Self Agent, so the Hub computer also appears on the wall and can be controlled like the other computers.

The hub/, client/, runtime-core/, and web/ folders in this package are generated copies. Edit the source packages and run node packages/livedesk/scripts/sync-web-dist.js before building or packing the product. The published livedesk package owns both runtime roles; the source-only @livedesk/client workspace is not a runtime dependency.

VuvoDesk's top runtime contract is transmission performance together with long-running stability. A faster path is not accepted if it permits duplicate capture helpers, stale monitor generations, unbounded frame queues, or an unproven Direct/P2P/relay transition. Release builds run the same lifecycle, transport recovery, and browser H.264 population gates used by CI.

Unified launch

npx -y --prefer-online livedesk@latest

The first interactive launch asks whether this computer is a Hub or Client. The selected role and stable device identity are cached in ~/.livedesk/device-role.json and ~/.livedesk/device.json. When a Supabase device role is available, it takes precedence over the offline cache.

For development and migration checks, the role can be forced for one run:

npx -y --prefer-online livedesk@latest --force-role hub
npx -y --prefer-online livedesk@latest --force-role client

Hub

npx -y --prefer-online livedesk@latest hub

This starts the VuvoDesk Hub, opens the local screen wall, accepts clients, and connects one local Self Agent through loopback TCP. The Self Agent reuses the Hub computer's stable device identity and does not open another login or status page. Hub shutdown, update, and role change drain that exact Agent tree before the launcher exits or hands off. The Hub UI/API listens on 127.0.0.1 by default while the client endpoint continues to listen on the LAN.

On startup, the launcher checks the Hub ports (5179 and 5197), identifies stale VuvoDesk Hub processes from their Node command line, stops each PID only once, waits for the ports to be released and bindable, and then starts the new Hub. Unrelated processes are preserved and reported with their PID, name, and command line. The client endpoint remains fixed at TCP 5197 by default so firewall rules, router forwarding, and direct clients keep a stable contract. Pass --no-clean to disable the startup cleanup explicitly. If a child Hub still loses a startup race with EADDRINUSE, the launcher performs one cleanup and startup retry, then exits without looping.

Client compatibility

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

The client form remains as a legacy compatibility alias. It records the Client role and uses the same unified runtime lock. The client signs in with Google, discovers the active Hub, and connects to the wall. Installed Windows, macOS, and Linux desktop apps start automatically after sign-in by default, reuse the saved session, and reconnect without opening the window. Turn this off in Settings > Desktop app when a computer should remain manual.

macOS physical diagnostic

On a Mac with two connected displays, stop every running VuvoDesk runtime, start visibly different continuously moving content on both displays, grant Screen Recording and Accessibility permissions, then explicitly confirm that the motion is already running:

npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion

This command branches before role resolution, state migration, and the normal runtime lock. It refuses to overlap an existing VuvoDesk runtime or capture helper, and normal macOS startup reciprocally refuses an active diagnostic lease. The lease owner authorizes exactly one direct-child production unified Hub launcher and one direct-child production unified Client launcher using the lease PID, parent PID, and token, then each launcher consumes and removes that capability before starting descendants. The Client therefore runs the normal Client bootstrap and starts its normal RemoteFast child instead of testing RemoteFast in isolation. All state and network discovery remain isolated. Cleanup joins those exact launcher roots after their Hub, RemoteFast, and ScreenCaptureKit descendants drain. Ctrl+C and termination signals join the same owned cleanup before exit. The default JSON report is written to one final path after cleanup, and run/cleanup errors always produce a failed result. It is written under ~/.livedesk/diagnostics. To select a path relative to the directory where the command was invoked:

npx -y --prefer-online livedesk@latest diagnose mac-physical --confirm-active-motion --report ./mac-result.json

Use diagnose mac-physical --help to inspect requirements without starting a runtime or changing cached role/account state. The confirmation flag is not treated as proof by itself: each display must also show two different decoded pixel hashes while native capture/compression/stdout counters advance at the active cadence. Diagnostic ffmpeg observers run sequentially after product CPU/RSS/process sampling, are labeled as diagnostic observers, and are excluded from those product budgets. Product resource evidence covers both unified launcher roots plus the Hub, RemoteFast, and ScreenCaptureKit descendants. VideoToolbox ownership comes from native active and terminal telemetry. The terminal v4 record must match the exact final restored-Wall helper observation, PID, profile, start time, capture generation, purpose, and stream, and must be newer than that stream's stop request. Its PID must equal the single OS helper sampled at that exact restored-Wall ready point; an earlier aggregate PID sighting is insufficient. A stale/ownerless/internal-only terminal record or a retired helper process alone is not accepted as encoder-session cleanup proof.

Physical transport diagnostic

While the local Hub is running and at least one Client is sending a current Mode 3 H.264 stream, run:

npx -y --prefer-online livedesk@latest diagnose transport-physical

The diagnostic proves one unchanged stream identity through Direct TCP, encrypted UDP P2P, encrypted relay, and Direct recovery. Every phase requires an independently decodable SPS/PPS/IDR frame observed by the Hub within a bounded deadline. It uses an exact-owner temporary lease, changes no firewall or router settings, and writes a redacted report under ~/.livedesk/diagnostics. Use diagnose transport-physical --help for device, Hub URL, timeout, and report-path options.

Frame modes

• Mode 2: independent 320x180 RGB565+LZO tiles for large, stable walls.
• Mode 3: direct hardware H.264 for focused remote control up to 4K.
• Mode 4: client Mode 2 inputs composited by an isolated Hub worker into one bounded H.264 Atlas stream, then split by UV into the normal browser slots.

Plans

• Free: 5 personal devices with a standard wall banner ad.
• Plus LTD launch: 30 personal devices, no ads, USD 79 one-time.
• Pro LTD launch: commercial use and larger walls, no ads, USD 199 one-time.

Monthly and yearly subscriptions are planned after the LTD launch.

Free ad slot

Free accounts show a standard bottom ad slot. Set these Vite build variables for a real AdSense placement:

VITE_LIVEDESK_ADSENSE_CLIENT=ca-pub-...
VITE_LIVEDESK_ADSENSE_SLOT=...

Without those values, VuvoDesk renders a neutral sponsored-placement placeholder so the free-plan layout can still be tested.