Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Xpra HTML Client

This is an (unofficial) clone of the Xpra HTML5 client.

It consists of a library and a frontend to connect to remote Xpra servers to view X11 sessions inside the browser.


The differences here are:

  • ES6+
  • Bundled
  • Refactored
  • Non-blocking (whenever possible)
  • Separate client module
  • Separate frontend example

You can try this yourself at (you need to set up an Xpra server yourself).



This code is compiled for browser support. Requires Node 8 or later to compile.


  • This might not compile on Windows.
  • Note, you have set up your own Xpra server to connect to.


To be able to use the Xpra HTML5 features, you need the following dependencies on your host system:

  • X11
  • pam
  • dbus
  • alsa
  • pulseaudio
  • python


If you want to run this on your server with a frontend. Clone this repository and perform the following commands:

First set up some dependencies:

git submodule init
git submodule update
cd lib/aurora.js
npm install
make browser

Then proceed with building:

npm install
npm run serve

This will build and start the example/ application.

Runs by default on http://localhost:9999/


If you're using this as a library:

npm install --save-dev xpra-html5-client

Then in your source:

import {createClient} from 'xpra-html5-client';

const client = createClient({/* Configuration */});

client.on('ws:open', () => console.log('Connected!'));

  // This is the same as configuration in createClient()
  // Ex. You can specify your defaults above and pass on any options you want to set in the login form here
  uri: 'ws://localhost:10000'

See example/ for an example (which can be served with the installation below).



Name Type Default Value Description
uri String ws://localhost:10000 Full URI for server websocket connection
reconnect Boolean true Enable reconnection attempts
notifications Boolean true Enable notification support
clipboard Boolean false Enable clipboard support (not supported)
sound Boolean true Enable sound support
bell Boolean true Enable system bell
printing Boolean false Enable printing support
transfer Boolean false Enable file transfer support
keyboard Boolean true Enable keyboard support
share Boolean true Share session (multiple connections)
steal Boolean true Steal session on create
language String Auto Language (keyboard)
username String Username


Name Type Default Value Description
dpi Number Auto Screen DPI
screen Number[2] Audo Screen size
audio_framework String Auto Audio framework (stream/mediasource/aurora)
audio_codec_blacklist String[] [] Blacklist audio codecs
audio_codecs String[] Auto Force a set of audio codecs
image_codecs String[] Auto Force a set of image codecs
compression_level Number 1 Compression level (1-10)
zlib Boolean true Use Zlib compression
lz4 Boolean true Use LZ4 compression


These are the methods exposed by the created client.

Method Description
connect() Connects to Xpra
disconnect() Disconnects from Xpra
ping() Pings the server
send(...packet) Sends a packet to server
inject(ev wid?) Injects an event to a surface
on(name, callback) Register an event handler
off(name, callback) Unregister an event handler
surface.focus(wid) Focuses (raises) a surface
surface.kill(wid) Kills a surface
screen.resize(w, h) Resizes the screen on remote
console.log(...) Sends a log message Sends a info message
console.debug(...) Sends a debug message
console.warn(...) Sends a warn message
console.error(...) Sends a error message


You can handle the events in the bus using the .on() API method.

* is the event names coming from the Xpra packets. See official documentation for more information.

Signature Description
ws:open => (ev) Connection opened
ws:close => (ev) Connection closed
ws:data => (ev, data) Data received
system:started => () Startup complete
system:bell => () System bell
system:url => (url) URL Open request
system:upload => (options, data) File was sent to client
system:print => (options, data) Print was sent to client
window:create => (<surface>) Window surface created
window:metadata => (<surface>) Window metadata changed
window:icon => ({wid, src}) Window icon changed
window:destroy => (<surface>) Window destroyed
window:focus => (<surface>) Window focused (raised)
window:blur => (<surface>) Window blured
overlay:create => (<surface>) Overlay surface created
overlay:destroy => (<surface>) Overlay destroyed
notification:create => (id, options) Notification create request
notification:destroy => (id) Notification destroy request
* Raw Xpra packet events


The library is compiled as as UMD, so you can use this directly in the browser using a CDN or loading the build/ file(s), then use the global window.XpraHtml5Client to access the APIs.

To launch an application in Xpra, use this as an example:

xpra --no-daemon --bind-tcp= --start=firefox --html=on start :10

If you want to be able to connect externally use --bind-tcp=

Working Features

  • Connection
  • WebWorker packet handler
  • Image decoders (jpeg/png/rgb/rgb32)
  • Sound decoders (stream/mediasource/aurora)
  • Compression (lz4/zlib)
  • Surfaces (window/overlay)
  • Mouse input
  • Keyboard input
  • Sound output
  • System bell
  • Notification forwarding
  • Window handling
  • Server console


  • Fix authentication (not working in main code either)
  • Full desktop forwarding
  • SSL Support
  • Print forwarding
  • File forwarding
  • Clipboard forwarding
  • Window move/resize (incl. server side)
  • Finish input support
  • Finish platform capability detection
  • Experimental video codec renderers


See LICENSE file(s)