feat(lume): auto-generate VNC credentials and deliver via SSH - #1207
Merged
Conversation
…scovery Rewrite the VNC backend to use Twisted's global reactor directly instead of vncdotool's api.connect(), which deadlocks inside uvicorn/asyncio on Python 3.13. Each VNC operation now creates a fresh connection via reactor.callFromThread() with threading.Event synchronization. Add VirtioFS-based VNC port discovery: lume creates a shared "lume-config" directory, writes vnc.env (port + password) after VNC starts, and the guest reads it on boot — eliminating hardcoded VNC port/password defaults. Key changes: - vnc.py: global reactor pattern, @defer.inlineCallbacks closures, manual drag (replaces mouseDrag/doPoll), client.screen fix - VM.swift: VirtioFS lume-config share, VNC URL parsing fix (URLComponents with vnc:// → http:// replacement) - cli.py: only override CUA_VNC_PORT from CLI when explicitly provided - setup-cua.sh: renamed from setup-cua-computer.sh, added "already mounted" check for lume-config VirtioFS share Tested E2E: 19/19 operations passing (screenshot, click, type, scroll, drag, hotkey, cursor position, screen size).
- Fix isort ordering in vnc.py (twisted.internet imports) - Add vncPassword parameter to MockVM.run() to match VM superclass - Regenerate lume CLI and HTTP API reference docs
- vnc.py: close client.transport in finally block of _with_client() to prevent TCP connection leaks accumulating over multiple operations - VM.swift: remove old vnc.env before starting VM so the guest can't read stale port/password from a previous run
macOS TCC blocks LaunchAgent processes from reading VirtioFS mounts
("Operation not permitted"), so the start_server.sh VNC config discovery
now uses a priority-based approach:
1. Local vnc.env (~/.cua-server/vnc.env) — written by host via
`lume ssh` or cached from a previous VirtioFS read. Not subject
to TCC restrictions.
2. VirtioFS lume-config mount (fallback) — tries direct read, then
sudo -n, and caches locally on success.
Also removes the sudoers entry approach (unreliable in LaunchAgent
context) and fixes the log output to show actual VNC target values.
After VNC starts, lume now spawns a background task that waits for SSH to become available and writes vnc.env directly to ~/.cua-server/ inside the VM. This works around macOS TCC blocking LaunchAgent processes from reading VirtioFS mounts. The SSH write is best-effort and silent — if SSH is disabled on the VM, it gives up quietly after ~30s. The guest can still discover VNC config via VirtioFS or use hardcoded defaults as fallback.
Use a generic location (~/.vnc.env) that doesn't depend on cua-server being installed. Keeps lume's VNC config delivery decoupled from cua-specific paths.
Lume now auto-generates a random VNC port and password for each VM and delivers them to ~/.vnc.env via SSH. Remove all hardcoded "lume" VNC password and 5901 port defaults from setup-cua.sh: - Remove hardcoded HOST_VNC_PORT=5901 and VNC_PASSWORD=lume defaults - Remove VNC port/password from LaunchAgent plist env vars - Make websockify read VNC port from ~/.vnc.env via wrapper script - Mark --host-vnc-port and --vnc-password flags as deprecated - Update comments and final output to reflect auto-config approach
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThis PR updates Lume documentation to version 0.3.0, replaces the legacy macOS CUA setup script with a comprehensive new installer adding VNC/noVNC support with websockify integration, and threads VNC password support through the entire stack from CLI commands down to the Python backend while refactoring the VNC handler to use per-operation connections instead of persistent ones. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant CLI as CLI (Run.swift)
participant Ctrl as LumeController
participant VM as VM.swift
participant VNC as VNCService
participant Host as Host System
participant Guest as Guest VM
participant SSH as SSH Client
User->>CLI: lume run --vnc-port 5900 --vnc-password secret
CLI->>Ctrl: runVM(..., vncPort: 5900, vncPassword: "secret")
Ctrl->>VM: run(..., vncPort: 5900, vncPassword: "secret")
VM->>Host: Create lume-config VirtioFS dir
VM->>VNC: setupSession(port: 5900, password: "secret")
VNC->>Host: start(port: 5900, password: "secret")
Host->>Host: Use provided password or generate
Host->>Host: Extract port/password from vnc:// URL
Host->>Host: Write vnc.env locally
Host->>Guest: writeVNCConfigViaSSH() with retry
SSH->>Guest: Poll for IP, SSH availability
SSH->>Guest: echo VNC_PORT/VNC_PASSWORD >> ~/.vnc.env
Guest-->>Host: VNC config written (best-effort)
Host-->>User: VNC session ready
sequenceDiagram
participant Handler as VNCHandler
participant Conn as _VNCConnection
participant ThreadPool as asyncio.to_thread
participant Factory as VNCDoToolFactory
participant Reactor as Twisted reactor
participant VNC as VNC Server
Handler->>ThreadPool: drag_to(start, end)
ThreadPool->>Conn: drag_to(start_x, start_y, end_x, end_y)
Conn->>Factory: _with_client(drag operation)
Factory->>Reactor: Create fresh connection per operation
Reactor->>VNC: Connect
VNC-->>Reactor: Client ready
Conn->>VNC: mouseDown(button)
Conn->>VNC: mouseMove(intermediate_x, intermediate_y) [stepwise]
Conn->>VNC: mouseMove(end_x, end_y)
Conn->>VNC: mouseUp(button)
Factory->>Reactor: Close transport
Reactor-->>Conn: Operation complete
Conn-->>Handler: Return
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
📦 Publishable packages changed
Add |
Contributor
📦 Publishable packages changed
|
This was referenced Mar 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
--vnc-password lume)~/.vnc.envinside the VM via SSH, bypassing macOS TCC restrictions that block VirtioFS reads from LaunchAgent processes~/.vnc.envDetails
macOS TCC blocks LaunchAgent processes from reading VirtioFS mounts (
Operation not permitted), so the previous VirtioFS-only approach for delivering VNC config to guest VMs didn't work reliably. The new approach:~/.vnc.envvia SSH after VM boot (background task, 6 retries × 5s, silent on failure)start_server.shandwebsockifyboth read from~/.vnc.envEach VM gets a unique random VNC port + password, ensuring VMs can't access each other's VNC servers.
Test plan
lume run~/.vnc.envcorrectlySummary by CodeRabbit
New Features
Documentation