cmux-vnc-here

Share this Mac's screen in one command — no VNC setup, no System Settings, no passwords to invent.

npx cmux-vnc-here

Spins up a throwaway, token-auth VNC (RFB) server and prints a vnc:// link + QR code. Open it in native macOS Screen Sharing (⌘K in Finder → paste the link, or scan the QR from another Mac) and you're looking at — and controlling — this machine. Hit Ctrl-C and the server, token, and screen access vanish.

It's the cmux-ssh-here idea for the screen instead of the shell: a full RFB 3.8 server hand-rolled in one file, using the standard VNC Authentication that Screen Sharing speaks — so the device you connect from needs nothing installed.

Why

• ⚡ Zero setup — one npx command; no enabling Remote Management, no vncpassword.
• 🍎 Native client — connects with the Screen Sharing app built into every Mac.
• 🔑 No credentials to share — auth is a one-time 8-char token baked into the link.
• ⏳ Self-expiring — the token rotates every 3 minutes; leaked links go stale on their own.
• 🎯 One-time mode — --once locks the link to the first device that connects.
• 👀 Live dashboard — current link, QR, countdown bar, and who's connected.
• 🧹 Nothing left behind — no system settings touched; close the terminal and it's gone.

Permissions (one-time)

The screen grab uses Apple's own screencapture, and keyboard/mouse control uses a native input module. macOS will ask your terminal app for two permissions on first run — grant both in System Settings → Privacy & Security:

• Screen Recording — to see the screen.
• Accessibility — to move the mouse and type.

How it works

• A from-scratch RFB server over TCP (speaks both the 3.3 security handshake that macOS Screen Sharing negotiates and the 3.7+ list form): ProtocolVersion → VNC Authentication (DES challenge-response; the token is the password) → ServerInit → framebuffer loop.
• Screen frames come from screencapture -t bmp (uncompressed, top-down, 32bpp BGRA — same layout as the wire, so no image-decode step), downsampled from Retina to the logical screen size and sent as Raw rectangles.
• Keyboard/mouse events are injected with @hurdlegroup/robotjs (robotjs's own screen capture segfaults on recent macOS, so it's used for input only).
• The token rides in vnc://:<token>@host:port and is rotated every CMUX_VNC_TTL seconds (default 180). --once freezes it after the first connection.

Options

| | | | --- | --- | | --once | Lock the link to the first device that connects; reject the rest. | | CMUX_VNC_TTL=<sec> | Token/link lifetime before rotation (default 180). | | PORT=<n> | Bind a fixed port (default: random free port). | | CMUX_VNC_DEBUG=1 | Log protocol events instead of the live dashboard. |

Security

⚠️ The token grants full screen + keyboard + mouse control as your user. It's a bearer secret — use it on a trusted LAN only, never over the open internet. The server binds 0.0.0.0, so anyone on your network who has the live token can connect. Use --once, and close the terminal when you're done.

Limitations

• macOS host only (uses screencapture + macOS input). The client can be any Mac.
• Primary display only, and one Raw full-frame per request (~3–4 fps on LAN, no compression or dirty-rect diffing). Fine for "show me the screen"; it's not video.
• 8-character password — a hard limit of the legacy VNC auth scheme.

License

MIT