Skip to content

Access via VS Code

This guide explains how to connect VS Code directly to an NCShare compute node using the Remote - SSH extension. The connection automatically requests a CPU or GPU allocation through Slurm, so you do not need to run salloc or srun manually or keep a terminal session open. This is the recommended way to use VS Code on NCShare as Remote - SSH sessions do not belong on the login node. This method uses a session "heartbeat" monitor to automatically terminate the Slurm job after a period of inactivity or when VS Code is exited, so you do not need to manually cancel the job.

Do not point Remote - SSH at the login node

Remote - SSH starts a VS Code Server on the node, which indexes your workspace, watches every file in the tree, and runs language servers. On a large directory this is often several cores and gigabytes of memory, even in a session opened only to run squeue, so light interactive use is not light load. Use the compute node profiles below.

Running an AI coding agent in VS Code

An agent running inside a VS Code extension inherits this connection, so its commands already run on the compute node and no extra setup is needed. The AI Use Policy still applies to what the agent does. If you instead run an agent from your own terminal, or from an interactive Slurm session on NCShare, see Access via AI Agents.

Cursor and other VS Code forks

This setup also works with VS Code forks such as Cursor and Windsurf, since the SSH configuration is independent of the editor. These editors ship their own Remote-SSH extension in place of Microsoft's so install that one instead.

Prerequisites

  • An NCShare account with SSH key access already configured. See Access via SSH if you haven't set this up yet.
  • VS Code installed locally.
  • The Remote - SSH extension installed in VS Code.

Step 1: Add SSH Config Entries

Add the following Host block to your local machine's ~/.ssh/config. Replace NCSHARE_UID with your NCShare UID.

Host ncshare-cpu
    User NCSHARE_UID
    ProxyCommand ssh -o StrictHostKeyChecking=accept-new %r@login.ncshare.org bash /usr/local/bin/ncshare-ssh-proxy.sh
    StrictHostKeyChecking accept-new 
    UserKnownHostsFile /dev/null
    ServerAliveInterval 30

If you have multiple SSH keys, specify the key to use by adding IdentityFile <path-to-ssh-key> to the Host block above. For example,

IdentityFile ~/.ssh/id_ed25519

Warning

We encourage encrypting your SSH private key with a strong passphrase. Never share your SSH private key with anyone.

Step 2: Configure VS Code's Connection Timeout

Submitting and waiting for a new Slurm job can take longer than VS Code's default 15-second SSH connect timeout.
In VS Code, run Cmd+Shift+P → Preferences: Open User Settings (JSON) → add the following to settings.json,

"remote.SSH.connectTimeout": 300

This gives the proxy script enough time to wait for a job to start (up to --wait seconds, 240 by default) before VS Code gives up.

Step 3: Connect

  1. Open VS Code and open the Command Palette (Cmd/Ctrl+Shift+P).
  2. Run Remote-SSH: Connect to Host...

  3. Select ncshare-cpu from the list.
    vscode-20260719234231815

  4. VS Code opens a new window and connects. The first connection for a profile submits a Slurm job and may take a few seconds, depending on resource availability. Later connections reuse the running job and connect immediately.

Requesting a GPU session

If you would like to request a VS Code session with GPU resources, add a ncshare-gpu profile to your ~/.ssh/config and pass in the partition and GRES flags,

Host ncshare-gpu
    User NCSHARE_UID
    ProxyCommand ssh -o StrictHostKeyChecking=accept-new %r@login.ncshare.org bash /usr/local/bin/ncshare-ssh-proxy.sh --name gpu --partition gpu,interactive-gpu --gres gpu:h200:1 --time 1:00:00
    StrictHostKeyChecking accept-new
    UserKnownHostsFile /dev/null
    ServerAliveInterval 30

If you are from an NCShare NSF GaaS partner institution, you may additionally include a host for the gpu-hp partition. Replace duke_h200_hp with your institution's high-priority QoS.

Host ncshare-gpu-hp
    User NCSHARE_UID
    ProxyCommand ssh -o StrictHostKeyChecking=accept-new %r@login.ncshare.org bash /usr/local/bin/ncshare-ssh-proxy.sh --name gpu-hp --partition gpu-hp --gres gpu:h200:1 --mem 128G --qos duke_h200_hp
    StrictHostKeyChecking accept-new
    UserKnownHostsFile /dev/null
    ServerAliveInterval 30

Customizing your Session

Set these options as flags in the ProxyCommand in ~/.ssh/config.

Flag Default Meaning
--partition common Slurm partition(s) to submit to (comma-separated list)
--account (none) Slurm account, if required by your partition
--qos (none) Slurm QoS, if required
--gres none GPU request, e.g. gpu:1, gpu:h200:1; none = CPU-only
--cpus 2 CPUs to allocate
--mem 4G Memory to allocate
--time 8:00:00 Hard wall-time cap on the job
--idle-min 15 Minutes of no connection before idle cleanup (0 disables idle cleanup)
--wait 240 Seconds to wait for a new job to start
--name vscode Profile name; each name gets its own job
--log /dev/null Where to send Slurm job stdout/stderr (set a path to debug)

For example, add --mem 128G to the GPU profile's ProxyCommand to request 128 GB of memory.

--idle-min 0 disables auto-cleanup

Setting --idle-min 0 prevents the watchdog from ending an idle job. The allocation remains active until you cancel it or it reaches the --time wall-time limit (8 hours by default).

Ending a Session

Closing the VS Code window (or disconnecting) stops the heartbeat. As long as --idle-min is not 0, the watchdog running inside the job notices the heartbeat has gone stale and ends the job itself after that many idle minutes (default 15 minutes). Manual cancellation with scancel is not required.

To end a session immediately instead of waiting for the idle timeout, or if you set --idle-min 0, SSH to the login node directly and cancel the job,

ssh NCSHARE_UID@login.ncshare.org
squeue -u $USER
scancel <jobid>

How it Works

A conventional VS Code Remote - SSH configuration connects to the NCShare login node. The login node is a shared entry point, intended for file management and job submission. A Remote - SSH session is not a comparable load as the VS Code Server it starts indexes the workspace, watches the file tree, and runs language servers regardless of what you do in the editor. The configuration described here moves that server onto a compute node.

The required scripts, ncshare-ssh-proxy.sh and ncshare-session-watchdog.sh, are installed centrally in /usr/local/bin.

In this configuration, an SSH ProxyCommand runs ncshare-ssh-proxy.sh on the login node whenever you connect to an alias such as ncshare-cpu. The script,

  1. Reuses a running Slurm job associated with the requested profile, such as cpu or gpu.
  2. Submits a new job if no matching job is running, then waits for its allocation.
  3. Proxies the SSH connection to port 22 on the allocated compute node.

The Slurm job runs ncshare-session-watchdog.sh. While an SSH connection is active, the proxy script updates a heartbeat file. After all connections close and the heartbeat becomes stale, the watchdog ends the job after the configured idle period, releasing its resources. Setting --idle-min 0 disables idle-based cleanup and the job continues until manually cancelled or its configured wall-time limit is reached.

Multiple profiles

Each SSH host, such as ncshare-cpu or ncshare-gpu, can use a distinct --name. This allows separate CPU and GPU sessions to run simultaneously without reusing each other's allocations.

The diagram below traces a single connection, from the ProxyCommand on the login node through to the VS Code Server running inside the Slurm job.

Connection flow from VS Code to an NCShare compute node through ncshare-ssh-proxy.sh and ncshare-session-watchdog.sh

Troubleshooting

VS Code prompts for a password instead of connecting

Check that your ProxyCommand explicitly includes NCSHARE_UID@login.ncshare.org. Without it, the inner SSH hop uses your local machine's username instead of your NCShare UID. Additionally, ensure you have SSH-keys set up for password-less login to the cluster.

Connection hangs, then times out around 15 seconds

Make sure "remote.SSH.connectTimeout": 300 is set in VS Code's settings.json.

Log shows a GPU warning and the job is queued for a long time

The proxy script checks GPU availability with sinfo before submitting and logs a warning (visible in VS Code's Remote-SSH output log) if none are free right now, along with what is currently free. Try a different --gres type, or wait. See the GPU Guide for more on GPU availability.

I want to see diagnostic information from job startup

Set --log to a real file instead of the default /dev/null, e.g. --log "/work/NCSHARE_UID/vscode-debug-%j.out", then check file after connecting.

Acknowledgements

This guide was adapted from PSC's Launching Remote IDEs on Bridges-2 Compute Nodes documentation and was enhanced with the help of Joe Shamblin of Duke CS.