Skip to content

Nested-display desktop sessions (Xephyr): watch the agent live with its own cursor #15

Description

@ElbertePlinio

Why

Watching a lab session today means opening a VNC viewer. When that feels like too much friction, the fallback is asking the agent to drive the real desktop — which warps the real cursor (no way around that on Wayland/X11: one pointer per seat).

A nested-display session type gives the Codex-like experience on your own screen: the lab display renders as a normal window on the real desktop. You watch the agent live, it has its own cursor inside that window, and your pointer stays yours.

Proposal

  • New option on session_create (type desktop), e.g. nested: true: start Xephyr :N -screen WxH instead of Xvfb when a host display is available.
  • Everything downstream stays identical — desktop_launch, desktop_click, screenshots, and VNC already only care about DISPLAY :N.
  • Detect Xephyr on PATH; fail with an actionable install hint like the existing Xvfb/x11vnc errors.
  • Keep Xvfb the default (headless/CI unchanged).

Notes

  • Wayland leak fix (apps escaping the lab display) landed separately — this issue is only about live viewing with an isolated cursor.
  • Open question: window title/branding for the Xephyr window, and behavior when the user closes it mid-session (should map to session error state like Xvfb death).

Checklist

  • nested option on desktop session create (CLI + MCP)
  • Xephyr detection + actionable error
  • Session status/destroy handles Xephyr like Xvfb
  • Tests (fake Xephyr binary, arg builder)
  • Docs + UNRELEASED.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions