How to Setup VScode with X11 in 5 Minutes

VScode is one of the most powerful tools for all programmers, which integrates perfect remote connection for all types of servers (Linux/Mac/Windows). Though you may have worked fluently with a pure command-line interface, sometimes a few GUIs could be handy and save your day. In this post, I’ll show you how I forward the GUIs using X11 forwarding.

This post is for:

  • People would like to access GUIs in their local laptop/machine from a remote server.

Prerequisite:

  • VSCode installed
  • Remote-ssh extension installed

Environment:

  • Local: MacBookAir M1 2021 (BigSur 11.3.1)
  • Remote: Ubuntu 20.04.4

1. Setup key-based authentication

To enable the VScode integrated X11 server connection, you must use the key-based authentication to connect to your server. If you have already set up this before, please directly head to the next step.

1.1 Create your local SSH key pair

ssh-keygen -t rsa -b 4096 -f $HOME/.ssh/id_rsa

This will generate ssh private-key at $HOME/.ssh/id_rsa and public-key at $HOME/.ssh/id_rsa.pub.

1.2 Register your ssh key to the remote server

PUBKEYPATH="$HOME/.ssh/id_rsa.pub" # the location of you ssh public key, should been generated in Step 1.1
HOST_NAME="192.168.1.1" # remote server address
HOST_PORT="22" # remote server port, if not configured leave it 22
USER_AT_HOST="XXXX" # your user name to log in remote server
ssh-copy-id -i "$PUBKEYPATH" -p "$HOST_PORT" "$USER_AT_HOST@$HOST_NAME"

If you type all the information correctly, the server will ask you to type the password once.

1.3 Configure VScode ssh connection

Type F1>ssh to VScode’s ssh configuration

If you don’t see HOST_NAME that looks similar to your remote host, paste below to the configuration file (Replace with your information):

Host My-Remote-Host
    HostName 192.168.1.1
    User XXXX
    Port 22
    IdentityFile ~/.ssh/id-rsa.pub
    ForwardAgent yes
    ForwardX11 yes
    ForwardX11Trusted yes

1.4 Test the key-based authentication

Reconnect to the remote server. Now you should be able to log in without typing password.

2. Setup X11 connection

Now let’s start configuring the X11.

2.1 Install remote X11 extension from the marketplace

There are two extensions:

  • Remote X11
  • Remote X11 (ssh)
    For ease, we just install both on the local and remote machine here.

2.2 Configure X11 settings

Now, use the remote-ssh extension to connect to the remote server. It should open up a new window. Open the marketplace of this new window, find Remote X11 (ssh), right-click and open the extension setting.

2.2.1 User (Local) Setting

For user setting, change the Authentication Method to keyFile. Also, provide the correct private-key path in

2.2.2 Remote (Server) Setting

Then, switch to the Remote tab. Scroll down and find Remote.X11.ssh:Host and Remote.X11.ssh:Port. Make sure these two match your server connection method.

2.3 Test the X11 host connection

Close the window and reconnect to the remote server. Open the Remote X11 (ssh) tab, if you see the below information, congratulation, you have successfully configured the X11 settings.

2.4 Install the local Xserver

Finally, to successfully “Draw” the received X11 locally, you’ll need to install the Xserver. Depending on your local environment, there are different open-source projects you can choose:

  • MacOS: Xquartz
  • Windows: Xming

2.5 Final test with xclock

After installing the Xserver, our final step would be testing a remote GUI.

xclock

You should see the remote GUI successfully forward to your local machine.