Shadow mode

August 8, 2026 · View on GitHub

Shadow mode gives remote access to an existing display session. It is useful when the applications are already running on a physical desktop and you need to see or control that desktop remotely.

Shadowing is supported on Linux, macOS, and Windows. On most platforms, the display must be active: it cannot be locked or turned off. Screen capture can also use substantially more CPU on the server and client than a regular Xpra session.

Start and connect

SSH one-liner

If Xpra is installed on the remote host and you can log in with SSH, start and attach to a temporary shadow server in one command:

xpra shadow ssh://HOST/

The shadow server stops when you disconnect. While it is running, it is also available through its Unix-domain socket, for example:

xpra info ssh://HOST/DISPLAY

Start from a shell

Start a persistent shadow server manually when you need to configure more options. This example exposes the main display on TCP port 10000:

xpra shadow :0 --bind-tcp=0.0.0.0:10000

On Windows and macOS there is no X11 display name such as :0, so omit the display argument. You can also omit it when the system has only one active $DISPLAY.

Security and session selection

The TCP example above is intentionally minimal and does not provide authentication or encryption. Configure both before exposing a shadow server beyond a trusted network.

Do not shadow an existing seamless or desktop session when you can attach to that Xpra session directly. Attaching preserves the session’s normal window and display handling and avoids capturing the screen again.

Diagnostics

Use -d ssh or another relevant category to enable debug logging. The shadow server also displays a system-tray menu while it is running and changes its icon when a client connects.

Shadow server tray menu

For more general diagnostic steps, see Debugging Xpra.

Related issues
  • #899 generic shadow improvements
  • #389 Windows shadow server improvements
  • #558 NVENC support for shadowing on Windows
  • #390 damage events for the POSIX shadow server
  • #391 macOS shadow server improvements
  • #530 resize shadow windows on the client
  • #972 fullscreen mode in the Xpra client
  • #1099 keyboard layout issue with the Windows shadow server
  • #1150 named pipes for Windows
  • #1321 scrolling with the macOS shadow server
  • #1322 resizing the macOS shadow screen