Skip to content

Getting Started

Requirements

  • CPython 3.13 or 3.14 with venv;
  • GNU Make, OpenSSH, and false locally;
  • access to the published ssh-wrapper wheel pinned in requirements.in when preparing the runtime;
  • the reviewed maintained-fork Xpra packages locally and remotely;
  • local system Python venv support (python3-venv on the supported systems);
  • a local graphical session and a remote Linux account capable of running the Wayland Xpra server.

Notifications, portal dialogs, native journal recording, GPU acceleration, and persistence have additional prerequisites. Elsewindow warns with the relevant host and package names when optional support is unavailable and continues with the affected feature disabled. It never installs system packages during startup.

Install the maintained package build with the reviewed install_xpra_release.py helper when the system does not already have a compatible Xpra installation. Generic upstream packages are not a supported substitute. See why the maintained fork is required and which upstream fixes were accepted, issue-driven, or retained only in the fork.

On amd64 Debian 13 or Ubuntu 26.04, review the helper before use. The streamed route is pending until the first reviewed main push:

( set -o pipefail; curl --proto '=https' --tlsv1.2 -fsSL 'https://raw.githubusercontent.com/kogeler/elsewindow/main/tools/install_xpra_release.py' | /usr/bin/python3 - )

Do not run the pipeline under sudo. The helper confirms the exact installed Xpra inventory through /dev/tty, validates the complete release and DEB capability payload, then invokes /usr/bin/sudo itself. It installs the local DEBs and their dependencies with APT rather than dpkg -i. To install a specific canonical release instead of the newest, append --release NAME (the release name or its exact tag) after /usr/bin/python3 -.

Install The Python Command

Install the latest published release with pip or pipx:

python3.14 -m pip install elsewindow
# or: pipx install elsewindow
elsewindow --help
elsewindow --prepare-xpra
elsewindow --diagnose

The version prepared by this source tree is recorded only in .version.

Prepare A Source Checkout

From this project directory:

make runtime-venv
./bin/elsewindow --help

The one make target prepares venv-runtime and a separate venv-xpra using the system Xpra interpreter, both beneath .venvs/<machine-user-key>/. Make and the repository launcher select this directory automatically from an application-specific hash of /etc/machine-id and the local UID. Each machine therefore prepares its own environments in a shared checkout. Run the same make runtime-venv command once on each machine; do not activate a venv manually. Old root-level environments are ignored and left untouched.

Ordinary launcher startup never creates an environment or invokes pip. It refuses to start when either environment is missing or stale. See the explicit setup command for the installed-package equivalent and the current-input validation contract.

This setup does not change the system xpra command or the shell's PATH. Elsewindow uses its prepared Xpra launcher, whereas a plain xpra opengl still checks the distribution's system Python and its installed modules.

After the first release, GitHub Releases also provide elsewindow-linux-amd64 and elsewindow-linux-arm64. Download the file that matches uname -m (x86_64 means amd64; aarch64 means arm64), verify it against the release's SHA256SUMS.txt, and set mode 0755. The executable bundles Python, Elsewindow, ssh-wrapper, and both YAML resources; it still requires system OpenSSH, false, Xpra, a graphical session, GPU/VA-API support where selected, and distribution packages.

chmod 0755 ./elsewindow-linux-amd64
./elsewindow-linux-amd64 --prepare-xpra
./elsewindow-linux-amd64 --diagnose
./elsewindow-linux-amd64 --ssh-alias agents-a -- xterm

Start An Application

Standalone setup uses its bundled dependency lock to prepare a separate local Xpra venv. It does not require this repository, Make, an Elsewindow venv, or installation into the system Python. Subsequent sessions only validate the environment; system Xpra and its Python venv support remain prerequisites.

With a trusted OpenSSH alias:

elsewindow --ssh-alias agents-a -- xterm

With a direct host:

elsewindow --host host.example --user desktop-user -- /usr/bin/xterm

Application arguments begin after --. To request the reviewed adaptive-alpha H.264 profile on the default gigabit LAN network profile while allowing only local-to-remote clipboard synchronization:

elsewindow \
  --ssh-alias agents-a \
  --encoding-profile h264 \
  --network-profile gigabit_lan \
  --clipboard=to-server \
  -- /opt/application/bin/application

The CLI reference owns every option, default, allowed value, and combination rule, including clipboard policy, logging, and persistent sessions. See the Xpra guide for runtime behavior, failure codes, and ownership limits.