Connecting VS Code to a Cluster

Introduction

If you use the ARC clusters at Oxford and want to use your local editor (such as Visual Studio Code) for editing and debugging code on the cluster, you’ll quickly find that you can’t just connect to the login node and launch VS Code’s Remote-SSH as you might on a regular remote server. In this post I’ll explain why you can’t launch VS Code directly on the login node, then walk you through the workflow: starting an interactive job, configuring SSH proxy-jump, and connecting VS Code to the interactive node. Note that while I’m talking about Oxford’s ARC cluster here, the general principles apply to working with VS Code on any remote cluster which has a low-compute resource login node.

1) Why you can’t launch VS Code directly on the login node

Here are the key reasons:

• The login/submit node of ARC (e.g., arc-login.arc.ox.ac.uk) is only for accessing the cluster and submitting jobs, not for doing interactive work like editing/building software or running analysis.
• Using the login node for builds, heavy compute, or interactive editing violates the cluster policy: “Login nodes should not be used for software build or compute tasks.”
• The correct node type for interactive work (including editing + lightweight builds) is an interactive node, not the login node.
• For VS Code, a recent update has added a verification step which requires installing node, and therefore requires more memory than is allowed for a single task on the login nodes of ARC (and other similarly structured HPC clusters).
• You used to be able to get around this using cursor, an AI-focused fork of VS Code, presumably because it didn’t have this check in place. However, the login nodes on ARC specifically limit file indexing capacity of processes so even if you’re able to get the remote extension to work, crucial things (e.g. git, search) don’t work.

In summary: the login node is the gateway, job submission hub — not your working node for remote-VS Code workflows.

2) Workflow for ARC: interactive job → proxy-jump → VS Code remote

Here’s how to use VS Code with ARC in a way that is compatible with the cluster architecture.

a) Start an interactive job

1. SSH to the login node:

  ssh <username>@htc-login.arc.ox.ac.uk

2. Request an interactive session on an interactive node. For example:

  srun -p interactive --pty /bin/bash

This will allocate a (shell) session on an interactive node with default resources, which is one non-gpu node. You can also specify particular resources at this step, e.g. if you wanted to develop against a gpu then you could append --gres=gpu:1, or even a specific kind of gpu, like an h100, say, with --gres=gpu:h100:1.
3. Once you are on the interactive node, you can load modules, build software, run test tasks, etc.
4. Make note of the hostname of the interactive node (you’ll use this for your SSH config).

Note here that I’m opting to use the arc-htc service (as I often would like access to a GPU) but the same principles apply to the regular ARC cluster.

b) Setup SSH config to use a ProxyJump

You want to configure your local ~/.ssh/config so VS Code’s Remote-SSH can indirectly reach the interactive node via the login node (jump host). Example:

  
  Host htc
    HostName htc-login.arc.ox.ac.uk
    User <username>
    ForwardAgent yes

  Host htc-interactive
    HostName <hostname-of-interactive-node>
    User <username>
    ProxyJump htc
    ForwardAgent no

where you’ve replaced <username> with your ARC username and <hostname-of-interactive-node> with the hostname of the interactive node you want to run on. We’ve got a few things going on here, so let’s unpack:

• ProxyJump is the core setting here, which tells ssh that when we want to ssh to htc-interactive it should first connect to the Host specified by the rule named htc, i.e. the top rule, and then subsequently connect, or ‘jump’, to the HostName specified in the htc-interactive rule. This intermediate connection is known as a proxy, so the whole thing is called a proxy jump.
• ForwardAgent is telling ssh to forward on our SSH agent to the remote location, so any keys that are loaded in your local ssh agent are also loaded on the remote machine. This can be useful when connecting to the login node on arc to be able to, for example, push commits to a remote repository with your local computer’s ssh key, but this can’t be forwarded to the vs-code server we’ll be running on the slurm interactive job, so we turn it off for the proxy jump rule. See here for a good explanation of ssh-agents and agent forwarding in general.

So once we’ve made those changes, we can utilise them in VS Code:

1. Install the Remote – SSH extension
2. Connect to the new Host in the ssh config file: Ctrl+Shift+P → Remote-SSH: Connect to Host… → htc-interactive

VS Code will establish the connection via the jump host and open a remote workspace on the interactive node.

c) Launch VS Code on the interactive node

• After connecting, VS Code will install a small server component on the interactive node and allow you to browse/edit files, open a terminal (this terminal is on the interactive node), and run/debug code there.
• Ensure you load your appropriate modules/environments, activate any virtual environments in your VS Code remote terminal (NOTE: this can be done automatically for you every time you log in by adding the commands you’d like to execute to your .bashrc).
• From the VS Code remote terminal you are effectively working on the interactive node (so you are inside the scheduler-allocated interactive job).

3) A little ssh-config hack

The eagle-eyed among you may have realised at this point the major flaw with the above strategy, namely that the hostname of the interactive node will probably change every time you need to ask for an interactive job. With the above setup you’d need to (potentially) edit your ssh-config every time, which would quickly become annoying, so instead we can use some ssh-config-magic to make the whole thing a bit more flexible.

We can replace the htc-interactive entry in our ssh-config with the following:

  
  Host htc-*
    HostName %h
    User <username>
    ProxyJump htc
    ForwardAgent yes
    

Here we’ve parametrised the HostName entry with the name of the rule using %h, and we’re using a wildcard in our Host name to match a pattern of potential hosts. To put it simply, any hostname we provide to ssh which matches htc-* (e.g. htc-051) will get this rule applied to it, and then this wildcarded hostname will be used as the final destination of our proxy-jump. In essence we can just connect to any interactive node on the htc cluster with a single command with no editing. For example, say that we’ve got an interactive job running on node htc-051 on ARC-HTC, we can just use this command:

ssh htc-051

to connect to it from our laptop, with a proxy-jump via the previously set-up htc rule pointing to the appropriate login node.

To use this in VS Code you will have to manually type in htc-051 when the remote-connection extension asks you which host you’d like to connect to, which I think we can agree is preferable to editing your ssh-config every time, or having a separate rule in your config for each possible node you might use!

4) Caveats and things to remember

There are some additional things to note when using this technique:

• The above ssh config rules can also be applied to work on ARC proper, rather than just the HTC cluster, by changing the Hosts and HostNames on the rules to use arc instead of htc.
• You will be asked for your ARC password and ssh-key passphrase (if set, which it generally should be) when logging in to a remote machine via the above ssh rules using VSCode.
• Interactive job time limits: keep an eye on how long your session is allowed to run; if you idle too long you might lose the session.
• Even though you’re editing remotely, you’re still subject to the cluster’s resource and environment constraints: module loads, file-system layout, network restrictions.
• You are not bypassing the scheduler by using VS Code — you are simply working inside an interactive session. This keeps you within the policy.
• If you need long-running builds or large resource tasks, you may want to submit a batch job instead of an interactive session.
• Make sure you’re comfortable working with the remote filesystem (e.g., your code/data resides on the cluster file system, you’re not editing a local copy).
• Use tmux or screen inside the interactive session if you expect to disconnect and want to preserve state.
• If you’re off-campus, ensure you’re connected via the university VPN (if required) so that SSH access works correctly.
• This technique seemingly does not work on BMRC due to differences in how the compute nodes connect to the internet.

Summary

Using VS Code with ARC via an interactive node & SSH ProxyJump gives you the flexibility and comfort of your local editor while remaining compliant with the HPC cluster architecture. You edit and run code inside a real allocated session on a compute-type node, rather than mis-using the login node.