SSH Remote Usage

Last update: 11 May 2023 [History] [Edit]

Use Case

If you have access to a CentOS 7 machine (through ssh) that you can use for code development, but you don’t have convenient interactive access to it, or don’t have administrator rights to it, this method is probably the most convenient way of using VS Code for ATLAS code development for you.

In this setup you can run VS Code on any one of its supported platforms (many flavours of Linux, macOS and Windows).


The requirements on the client side are very lightweight with this approach.


If you are connecting remotely (i.e. from outside CERN), please first have a look at ssh tunnelling below.

If you are running on Windows, you should also follow the Windows instructions on installing OpenSSH.

Press F1, and choose “Remote-SSH: Connect to Host…” (or possibly “Remote-SSH: Connect Current Window to Host…”), and enter the host that you want to connect to.

Once the connection is established (probably after you had to enter your password), make sure that all the extensions that you’ll want to use, are “enabled” on the remote host. Note that you do not need to do this on every connection, only during the first time that you are making use of the host.

Next you need to set up your work area. One convenient way is to open a new terminal from the VS Code top menu, and in that terminal set up a partial build of athena as you normally would. With something like:

cd <some appropriate place>
git clone ssh://<username>/athena.git
<set up the appropriate branch>
<create a package_filters.txt file>
mkdir build
cd build/
asetup <the appropriate release>
cmake -DATLAS_PACKAGE_FILTER_FILE=../package_filters.txt ../athena/Projects/WorkDir/

With that done, you can finally tell the application to open the freshly cloned athena repository for editing.

Note that when you do this, VS Code will “re-initialise” the connection. Meaning that you will (probably) have to re-enter your password, and the terminal that you used previously, will go away. Because of this, it can be a very viable option to do the initial setup of the work area on the remote host in a terminal independent of VS Code, and only once the repository and the build directory have been set up, connect to the host with the editor.

If you did everything correctly, now you can start editing the source files in the package(s) that you set up for the partial build.

Setup SSH tunnel

If you want to connect to a machine behind a firewall (for example, you want to connect to your CERN desktop from home) then you can do the following:


WarningIf you are on a Windows machine, you should first follow the Windows instructions to install an OpenSSH client and server.

You can now follow the standard setup instructions above, except using (or localhost) as the remote host to connect to. Specifically, you will need to click “Remote-SSH: Connect to Host…”, then choose ‘Add New SSH Host’ and then use the following ssh command : ssh -p 2222 USERNAME@127.0.01. You only need to do this once, as long as you save it in a .ssh/config file as prompted: next time, you can just select from the list.

Alternatively you can use ProxyJump option of ssh, for example


You have to type your password two times, the first time to lxplus, the second time to your remote machine. You can make it the default changing the your ssh configuration (usually in ~/.ssh/config) to include the following:

Host myremote

and then you can call connect to your remote machine simply with ssh myremote.

Multiplexing SSH for Lxplus

Lxplus uses a load balancer to direct SSH connections to different nodes. This can cause problems since VS Code connects several times when starting up. Thus it could start the server on one node, and be looking for it on another. SSH allows for multiplexing your connection, i.e., one connection is opened and all subsequent SSH requests will go through that initial connection. Thus you, and VS Code, always end up on the same initial node. Hopefully, resulting in a more stable setup.

You can enable this option using ControlMaster auto in your local ssh_config for your connection to lxplus. You can create a separate host entry if you don’t want to change all of your connections to lxplus. ControlPath is a location for the sockets and ControlPersist keeps the socket open for N seconds after the last connection is closed. An example snippet from an ssh_config where you would connect to host lxplus_vscode in VS Code:

Host lxplus_vscode
    user X
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p 
    ControlPersist 60  
    ... the rest of your entry ...

The only downside is that this does not work with SSH remote commands, which is experimentally supported by VS Code.