Third post of a series of three about running GUI applications on GitHub Codespaces.
The second post, GitHub Codespaces: Developing GUI Applications 2/3, showed you how to run a GUI application on a Codespace using VNC, this one will show you how to run a GUI application on a Codespace using X11 Server.
X11 (with forwarding)
The second way is to use X11 Server, and for which we will rely X11 forwarding, with forwarding we will be able to graphical interfaces of X11 programs running on a remote machine to be displayed on a local client machine without the need to have direct connectivity between the remote machine and the local machine. (X11 was designed from the start to be used over local network connection).
While this method is simpler to setup, and doesn’t place any load on the Codespace, it requires a X11 server on a machine you have access to (typically your machine, which we will consider for this example).
X11 server configuration
If you are using Linux (on a desktop) it is very likely that you already have a X11 server installed and running.
If you are using Windows you may need need to install one. If you are running Windows Linux Subsystem 2 then it has the capability to run X applications out of the box but you may need to configure it. See Run Linux GUI apps on the Windows Subsystem for Linux for more details.
If you are not running WSL2 you will need to install a X11 server. VcXsrv is a popular free choice and I’ve heard some praises on (paid) x410. (not endorsing any of them, just mentioning them as examples).
If you are using MacOS you will need to install a X11 server. XQuartz is a popular free choice.
I will personally use WSL2 for this example.
SSH configuration (client)
After you have a X11 server running on your machine, you need to configure SSH to forward X11 connections (using OpenSSH here, other clients configuration may be different) from Codespace to your machine.
Edit your SSH config file (
\config on windows and
/config in other systems) and add the following lines:
This will tunnel X11 connections over SSH.
Note: This will enable X11 forwarding for SSH to all HOSTS (because of the
*), which may not be advisable, specially on shared machines (which is not the case here). See the notice on ForwardX11 parameter description.
ForwardX11Trustedis required to allow X11 forwarding for remote hosts which are not trusted (which is the case here), it is recommended you set this value to
Noand take the effort to configure
XAuth(but will use
truehere for simplicity).
See ssh_config for more information (referencing OpenSSH docs which is the most used SSH client).
Connecting to the Codespace with SSH
SSH client configured, now all we need to do is connect to the codespace via SSH. For that we will use the GitHub CLI, if you don’t have it installed, now it’s the time to do it.
Note: This requires SSH server running on the Codespace, since we are using the default image, it is already running. But you may need to install a server. You can run
which sshdon the codespace to check if it is installed (not necessarly running though).
On your machine, execute the command
gh codespace ssh -c CODESPACENAME and you will be connected to the Codespace via SSH (if you omit the
-c CODESPACENAME then CLI will allow you to interactively select the Codespace you want to connect to).
Note: if when you login you get the message
X11 forwarding request failed on channel 0then you need to install
xauthon the Codespace. The simplest way wou can do that by adding the following line to your
devcontainer.jsonfile (when using a Debian/Ubuntu based image):
"postCreateCommand": "apt-get update && apt-get install -y xauth",
But there are other ways, like adding a
Dockerfile to your repository and installing it there, or installing it manually after you login to the Codespace.
I will leave it as an exercise for you to figure out the preferred way of doing it.
This is the
devcontainer.json file I used for this example (again using the default image):
"postCreateCommand": "sudo apt-get update && sudo apt-get install -y xauth x11-apps x11-common"
Note: You can integrate Codespaces with OpenSSH so you can remote into your codespaces without the need to call the CLI. see for more info.
DISPLAY environment variable
In order for X Apps to connect to the X11 server, they need to know where it is, for that they use the
DISPLAY environment variable (must X apps also allows to specify the display via command line parameters).
Most of the times you don’t need to set it since
SSH does it for you, run
Most of the times SSH will get it right, for example this is what I get when I run it on my Codespace:
$ echo $DISPLAY
So let’s try to run a X11 application, for example
xlogo, a simple X11 application that displays the X logo. (part of the
x11-apps package we installed earlier).
If all goes well you should see the X logo displayed on your machine and you can skip the next section (or read if you want to have a better understanding of
DISPLAY variable is not set or it’s incorrect you will see the following error:
Error: Can't open display: :0
It’s time to understand how to fix this, read the next section.
Setting DISPLAY environment variable
Once we login we will need to set the
DISPLAY environment variable to point to the X11 server. The value of the variable depends on the X11 server listening port. The value of environment variable follows the format
[hostname]:displaynumber[.screennumber] (you can omit hostname for localhost and the screen number if it’s zero)
The X server is listening on port 6000 + display number, SSH does the port forwarding for us, so (tipically) we just need to set the
DISPLAY variable to
:10, by default SSH will forward the X11 connection to port 6010 (6000 + 10) to avoid conflicts with other X11 servers running on the machine itself. This value is defined in the X11DisplayOffset setting in the SSH server configuration file (
/sshd_config), since in our case it is not defined then it uses the default value of
The display number is going to be must likely 10, but in case it isn’t, we can see which ports SSH is forwarning by executing the command
netstat -tunlp |grep ':60'' and look for the port 6000 + display number.
In the example below we can easily see that the display number is indeed 10.
$ netstat -tunlp |grep ':60'
(Not all processes could be identified, non-owned process info
will not be shown, you would have to be root to see it all.)
tcp 0 0 0.0.0.0:6080 0.0.0.0:* LISTEN -
tcp 0 0 127.0.0.1:6010 0.0.0.0:* LISTEN -
tcp6 0 0 ::1:6010 :::* LISTEN -
Based on the display number you have determined, set the
DISPLAY variable to the correct value, in the case above we should use
Now try again to run an X application.
You are done
Using X11 is remarkly simple, there is almost a zero effort to configure and there is no desktop to manage all windows will just blend with your desktop as if they were a native application, the only requirement is that you keep the SSH session open.