The Screen tab on a device’s Family page streams the monitored user’s desktop straight into the parent’s browser, live, while they use it. Under the hood it’s a per-session VNC server the daemon spawns on demand, tunneled through the existing CP↔node agent connection and exposed to the browser as a WebSocket the canvas reads from. No third-party relay, no extra port to open on the node’s firewall, no background recording. Live screen view is a Pro-tier capability — Free plans see the tab but the Start screen view button stays locked.

Requirements

The viewer is a generic VNC client wrapped in a WebSocket bridge, so the monitored user’s desktop needs a VNC-compatible server running inside their graphical session.

• The monitored user must be logged in with an active graphical session — Wayland or X11. Without an active session there is nothing to attach to and Start screen view errors out.
• For Wayland sessions, the node needs wayvnc on $PATH.
• For X11 sessions, the node needs x11vnc on $PATH.
• Both come from the distro’s package manager (apt install wayvnc / dnf install x11vnc / pacman -S x11vnc, depending on the distro). The Family daemon does not install them automatically — if the right binary is missing the session can’t start and the modal returns an error explaining which one is needed.

Starting a session

The flow is initiated entirely from the parent’s browser; the monitored user does not need to acknowledge or accept anything.

1. Open the device page in CP and switch to the Screen tab.
2. Pick a monitored user from the dropdown at the top of the tab. The dropdown lists only the users on this device that have Monitor turned on.
3. Click Start screen view. CP issues a Start request to the node; the daemon detects whether the user is on Wayland or X11, spawns wayvnc or x11vnc on a random free local port, and reports back the session id.
4. The viewer modal opens with a canvas in the middle. The browser opens a WebSocket to CP, CP proxies it down the agent tunnel to the node, and the node bridges it to the local VNC port. The first frame typically lands within a second or two.

The VNC server binds to localhost on the node — the random port is never exposed on the public interface. Everything you see in the canvas has travelled CP↔node TLS the whole way.

The recording badge

Live screen view is not covert. The monitored user always sees a clear indicator that someone is watching:

• The status-bar monitor indicator flips from its idle state (gray eye, “monitored”) to recording (red dot, “screen view active”) for the entire duration of the session.
• The login banner stays as-is — the same notice that’s posted to every monitored user about Family being active continues to show during a live view. Nothing about the banner suggests viewing is happening secretly because nothing about viewing is secret.
• There is no covert mode. The recording badge is part of the product contract — a parent cannot configure it away, and a hardened build cannot suppress it. If you want fully-undisclosed monitoring, this product is not for you.

View-only vs Allow control

By default a live session is view-only — frames come down, nothing goes up. A toggle inside the modal upgrades the session to full remote control.

• Default mode: view-only. Mouse movement, clicks, and keyboard input from the parent’s browser are dropped before they reach the WebSocket. The monitored user continues using their machine as usual; the parent just sees what they see.
• Toggle Allow control (mouse + keyboard). The toggle sits at the bottom of the modal. Flipping it on tells the bridge to start forwarding pointer and key events to the VNC server, so the parent can move the mouse, click, type, and otherwise drive the desktop as if they were sitting at it.
• The badge updates. While control is active, the recording banner gains a “You are controlling their input.” line so the monitored user is unambiguously aware that the parent has the keyboard and mouse, not just the screen.
• Same Pro gate covers both. In v1 there is no separate permission for view vs control — any parent who can open the screen tab on a Pro plan can flip control on. Per-parent permission granularity is on the roadmap.

Stopping a session

Closing the modal cleanly tears the whole stack down.

• The browser sends a Stop request to CP, which forwards it to the node.
• The daemon SIGTERMs the VNC server (wayvnc or x11vnc), waits for it to exit, and removes the session entry from the in-memory session table.
• The recording indicator on the monitored user’s status bar flips back to “monitored” (gray eye) within a tick.
• A screen_session_ended event is recorded against the device with the session duration in seconds. It shows up in the device’s audit log alongside policy edits and Monitor-toggle events, so there is a permanent record of who watched and for how long.

Automatic Stop on disconnect

The Stop request is the happy-path teardown — but the modal can also disappear ungracefully (the parent closes the tab, the laptop sleeps, the WebSocket dies mid-stream). The daemon does not need an explicit Stop to clean up:

• The Stop teardown is deferred on the WebSocket handler, so the moment the WS connection closes for any reason, the same cleanup runs — SIGTERM the VNC server, drop the session entry, flip the indicator back.
• There are no orphaned wayvnc / x11vnc processes left behind by a dropped connection. The next time the parent clicks Start screen view the daemon spawns a fresh server on a fresh port; nothing leaks across sessions.

What we don’t do

A few common questions about live viewing that this build answers no to:

• No background recording. The VNC server is only running while a parent is actively viewing. There is no daemon-side capture process that records the desktop when no one is looking.
• No frame storage, no replay history. Frames are streamed to the browser canvas and discarded. There is no server-side video file you can scrub back through later — the recording badge is literal, but what was recorded only existed in the parent’s browser for the duration of the session.
• No bandwidth shaping. The pipe is straight VNC-over-WebSocket through the CP↔node tunnel; there is no adaptive bitrate, no frame-rate cap, no quality slider. If the link is slow, the canvas is slow.
• No audio. VNC-over-WS does not carry audio in this build — you’ll see what the monitored user is watching but you won’t hear it.
• Encryption is only as strong as the CP↔node TLS. All traffic rides the same TLS tunnel CP uses for every other request to the node. If you’re running the node with a self-signed or weak cert, the screen stream inherits that posture. Set a real cert.

Where to next

• Family policies — author URL blocklists, app rules, bedtime windows, and daily screen-time budgets.
• Family stats — see what’s in the Timeline + Summary, including the screen_session_ended event this page generates.
• Family hardening — boot-path lockdown so a kid can’t sidestep the policies (and the screen view) by booting a different OS.