Xpra Documentation
Using Xpra
Xpra’s graphical tools cover the most common ways to start, find, and connect to sessions. Open Xpra from your desktop’s application menu to get started, or use the command-line examples below when you want a repeatable command or more control.
Start with the graphical tools
Choose a task from the main Xpra window. Each tool focuses on one part of setting up or using a session.
Xpra main window
Your starting point for browsing available sessions, connecting to a server, sharing an existing display, changing Xpra’s configuration, or starting a new session.
Connect to a session
Use Connect to enter a server address and credentials. You can save the connection to a session file so it is easy to reuse later. See the client guide for connection options.
Start a session
Use Start to launch an application in a seamless session, create a full desktop, or share an existing display. Sessions can run on this computer or a remote host.
Choose session features
The Options buttons in the Start window let you tailor clipboard sharing, notifications, system tray forwarding, input handling, audio, printing, and other session features.
Configure Xpra
Use Configure to change persistent defaults, check optional packages, tune picture compression, enable debugging, and configure server components. The settings can also be managed through configuration files.
Configure features
Choose which session features Xpra forwards, including audio, video, the system tray, files, printers, clipboard contents, notifications, and windows.
Command-line examples
These examples apply to the current versions.
Use man xpra for the manual matching your installed version. On Microsoft
Windows, see the Windows command line.
Simple seamless application forwarding
This is how Xpra is most often used. This command starts xterm (or any
graphical application of your choice) on HOST and displays it on your local
desktop through an SSH transport:
xpra seamless ssh://USERNAME@HOST/ --start-child=xterm
Step by step
Instead of starting and attaching to the session with a single command, first
connect to the server via SSH and start the Xpra server on a free display (:100
in this example):
xpra seamless :100 --start=xterm
Then connect to this Xpra instance from the client:
xpra attach ssh://USERNAME@HOST/100
Replace HOST with the hostname or IP address of the server.
Connecting locally
If you are attaching from the same machine with the same user account, this is sufficient:
xpra attach :100
If there is only one Xpra session running, omit the display:
xpra attach
Access without SSH
SSH provides host verification, secure authentication, and encryption. It is available on all platforms and is well tested.
If you do not want to give remote users shell access, or want to share sessions between multiple remote users, you can use TCP sockets:
xpra seamless --start=xterm --bind-tcp=0.0.0.0:10000
Assuming port 10000 is allowed through the firewall, connect from the client
with:
xpra attach tcp://SERVERHOST:10000/
This example TCP socket is insecure. See authentication before exposing it to a network.
Attach with a session file
Instead of typing the same attach command repeatedly, create a session file and double-click it to connect:
mode=ssh
host=YOURSERVER
speaker=off
See session files for more information.
Forward a full desktop
Start a full desktop environment with the desktop mode:
xpra desktop --start-child=fluxbox
You can connect via SSH, TCP, or any other supported transport.
Clone or shadow an existing display
Access an existing display remotely:
xpra shadow ssh://SERVERHOST/
Share the clipboard
Synchronize clipboard contents between the client and server while disabling the other forwarded features:
xpra shadow --clipboard=yes --printing=no --windows=no --speaker=no ssh://SERVERHOST/
Forward a printer
xpra shadow --printing=yes --windows=no --speaker=no ssh://SERVERHOST/
Local printers should then be available as virtual printers on the server.
More usage documentation
Go deeper into client options, performance, deployment, and troubleshooting.
Clients and configuration
- Client — launch and configure the Xpra client
- Client implementations — compare the available clients
- Terminal client — render windows in a terminal emulator
- Configuration — use configuration files
- Client OpenGL — improve client rendering performance
Graphics and diagnostics
- Server OpenGL — run accelerated OpenGL applications
- Picture encodings — tune encoding, including NVENC
- Logging — enable logs for debugging
- Security — harden an Xpra installation
Deployment
- Proxy server — provide a single entry point
- Apache proxy and Nginx proxy
- Windows Subsystem for Linux
- Xdummy — use the alternative virtual framebuffer
