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 method to use VS Code on NCShare, since the login node is not intended for computationally-heavy workloads. 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.

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 one Host block per profile required to your local machine's ~/.ssh/config. Replace NCSHARE_UID with your NCShare UID.

Host ncshare-cpu
    User NCSHARE_UID
    ProxyCommand ssh -o ConnectTimeout=300 NCSHARE_UID@login.ncshare.org 'bash /usr/local/bin/ncshare-ssh-proxy.sh --name cpu --partition common'
    ConnectTimeout 300
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    LogLevel ERROR
    ServerAliveInterval 30

Host ncshare-gpu
    User NCSHARE_UID
    ProxyCommand ssh -o ConnectTimeout=300 NCSHARE_UID@login.ncshare.org 'bash /usr/local/bin/ncshare-ssh-proxy.sh --name gpu --partition gpu --gres gpu:h200:1'
    ConnectTimeout 300
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    LogLevel ERROR
    ServerAliveInterval 30

If you are from an NCShare 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 ConnectTimeout=300 NCSHARE_UID@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'
    ConnectTimeout 300
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    LogLevel ERROR
    ServerAliveInterval 30

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 matches the ConnectTimeout 300 used above and gives the proxy script enough time to wait for a job to start 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, ncshare-gpu or ncshare-gpu-hp 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.

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 4 CPUs to allocate
--mem 16G 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. Login nodes are intended for file management, job submission, and other lightweight tasks; computational workloads should run on compute nodes.

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.

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, and that ConnectTimeout 300 is set in the matching Host block.

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 at Duke University.