VS Code Remote-SSH

Connect to HPC using VS Code Remote-SSH extension

Use VS Code on your local machine to connect to the HPC via the Remote-SSH extension. This approach runs VS Code locally while editing files and running terminals on the HPC.

For a browser-based VS Code experience running directly on a compute node, see VS Code Server on HPC instead.

Installation

  1. Install VS Code on your local machine
  2. Install the Remote - SSH extension from the marketplace

Optional useful extensions: Jupyter, Python, R, Markdown All in One, Rainbow CSV.

Connect to Head Node (Obsolete)

Configure SSH

Press Ctrl+Shift+P on PC (or Cmd+Shift+P on Mac), type in “Remote-SSH: Open SSH Configuration File” and click on it as soon as the complete line appears; then add:

Host hpc
    HostName <hpc_ip>
    User <username>

Replace <hpc_ip> and <username> with your actual HPC IP address and username, see CU_Neurology_HPC_Info_2026.md.

Connect

  1. Press Ctrl+Shift+P on PC (or Cmd+Shift+P on Mac), type in and select “Remote-SSH: Connect to Host”
  2. Select your HPC entry hpc, enter password, wait for connection to establish
  3. Browse files via “Remote Explorer” or File > Open Folder

The status bar at the bottom of VS Code shows your connection status.

Usage Tips

  • Open terminal: Ctrl+`
  • For R language support: pixi global install --environment r-base r-languageserver

Caveats

  • The head node has limited resources. Do not use VS Code to headnode.
  • Even just for text editing it can take can eat up a lot of resources on the login node If it’s initiated under a directory with lots of sub folder and files; so you should try to open a specific small folder if possible.

Connect to Compute Node

For computations, connect VS Code to a Jupyter server running on a compute node.

Step 1: Request Compute Node

In VS Code terminal (connected to head node):

srun --constraint="cpu2mem16a|cpu2mem16b" --mem=15G --pty bash

Step 2: Start Jupyter

Create ~/start_jupyter.sh once:

cat > ~/start_jupyter.sh << 'SCRIPT'
#!/bin/bash
PORT=$(shuf -i8888-8988 -n1)
rm -rf ~/.local/share/jupyter/runtime/kernel-*.json 2>/dev/null
echo "=========================================="
echo "Jupyter Lab on port $PORT"
echo "=========================================="
jupyter lab --no-browser --ip=0.0.0.0 --port=$PORT \
    --ServerApp.allow_origin='*' \
    --ServerApp.allow_remote_access=True \
    --ServerApp.disable_check_xsrf=True
SCRIPT
chmod +x ~/start_jupyter.sh

Then run:

./start_jupyter.sh

You should see output like:

==========================================
Starting Jupyter Lab on port 8891
==========================================
[I 2026-01-28 11:30:45.123 ServerApp] Jupyter Server 2.x.x is running at:
[I 2026-01-28 11:30:45.123 ServerApp] http://127.0.0.1:8891/lab?token=abc123def456ghi789jkl...

Copy the URL with token from the output.

Step 3: Forward Port(Optional)

  1. In VS Code, open the PORTS tab (bottom panel, next to TERMINAL)
  2. The port should auto-forward, or click “Forward a Port”
  3. Enter the port number shown in Jupyter output (e.g., 8891)
  4. Verify the port appears in the PORTS list

Note: This is optional since ssh -N -L script generated in the *.out has forwarded the port.

Step 4: Connect the Notebook

  1. After running the ssh -N -L command in the terminal on your local machine, you can access the Jupyter server in your browser at:

    http://127.0.0.1:8891/lab?token=abc123def456ghi789jkl...

  2. If you want to access the Jupyter Notebook from VS Code, follow these steps:

    1. Open your .ipynb file in VS Code (on your local machine).

    2. Click “Select Kernel” in the top-right corner of the notebook interface.

    3. Choose “Existing Jupyter Server.”

    4. Select “Enter the URL of the running Jupyter server.”

    5. Paste the server URL, replacing 127.0.0.1 with localhost:

      http://localhost:8891/lab?token=abc123def456ghi789jkl...

    6. Press Enter and choose a server name if prompted.

      • If the token is not included in the URL, you will be prompted to enter a password.
      • In that case, use the Jupyter token as the password.

VS Code will save the connection - you won’t need to re-enter the token for this session!

Troubleshooting

“Kernel does not exist” Error

Symptom: Error when running cells about kernel not existing

Solution:

  1. Click the kernel name in top-right corner
  2. Select “Select Another Kernel”
  3. Choose your Python environment again (creates fresh kernel)

Prevention: The script automatically cleans old kernel state on startup

403 Forbidden Errors

Symptom: 403 GET /api/kernelspecs errors in Jupyter output

Solutions:

  1. Verify you’re using the full URL with token
  2. Check the script includes --ServerApp.disable_check_xsrf=True
  3. Ensure --ip=0.0.0.0 is set (not 127.0.0.1)
  4. Try restarting Jupyter with the updated script

Connection Timeout

Symptom: VS Code can’t connect to Jupyter server

Solutions:

  1. Verify your srun job is still running: 
    squeue -u $USER
  2. Check you’re on the correct compute node: 
    hostname
  3. Verify port forwarding in VS Code PORTS tab
  4. Try manually forwarding the port if auto-forward didn’t work

Port Already in Use

Symptom: “Address already in use” error

Solution: The script should automatically finds an available port so this should not happen but if it does:

  1. Kill any existing Jupyter processes: 
    pkill -u $USER jupyter
  2. Run the script again

Job Time Limit Exceeded

Symptom: Jupyter suddenly stops, kernel disconnects

Solution: Request more time when starting:

srun --pty -t 8:00:00 ...  # 8 hours

Notes

  • Cost: Clean up when done: scancel <job_id>
  • Simpler alternative: VS Code Server runs entirely in browser with less setup