Skip to content

Visual Studio Code (code-server)

Running an interactive VSCode editor in the WI-HPC cluster requires SSH Tunneling to securely forward the code-server service from a compute node to your local machine.

Quick Summary:

  1. Request resources on a compute node (interactive srun or batch sbatch)
  2. Start code-server on the compute node
  3. Create an SSH tunnel from your local machine to the compute node
  4. Open the browser to http://localhost:8080

Warning

Always request resources when running Visual Studio Code, either via srun (interactive) or sbatch (scheduled). Ensure you request enough CPUs, memory, and runtime for your work. See Job Scheduling for resource options and queue limits.

Prerequisites

Before starting, ensure you have:

  • SSH access to the WI-HPC cluster (wi-hpc.wistar.org or your cluster domain)
  • The code-server module is installed on the cluster (ask your cluster admin if unsure)
  • A local terminal with SSH client installed (macOS, Linux, Windows Subsystem for Linux)
  • A web browser (Chrome, Firefox, Safari, or Edge)
  • Optional but recommended: tmux to keep your session alive if your SSH connection drops

Best for: Regular use, longer work sessions, ensuring your work is not interrupted.

The simplest and most reliable way is to submit a batch job using an sbatch script. This automatically:

  • Reserves resources for your session
  • Starts code-server and prints connection instructions
  • Keeps the session alive in the background

Step 1: Create a submission script

Create a file named launch-code-server.sh and save it locally:

#!/usr/bin/env bash
#SBATCH --job-name=code-server
#SBATCH --partition=defq
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=2
#SBATCH --mem=4GB
#SBATCH --time=08:00:00
#SBATCH --mail-type=begin,end,fail
#SBATCH --mail-user=username@wistar.org
#SBATCH --output=code-server-%j.out
#SBATCH --error=code-server-%j.err

# Load the code-server module
module load code-server/1.105.1

# Generate a random available port (range 8000-9999)
PORT=$(shuf -i 8000-9999 -n 1)

# Get the compute node hostname
HOSTNAME=$(hostname)

# Start code-server in background (--auth none for internal cluster use only)
code-server --auth none --bind-addr 0.0.0.0:$PORT &

# Wait a moment for the service to start
sleep 3

# Print connection instructions
echo "==========================================="
echo "code-server is running!"
echo ""
echo "Compute Node: $HOSTNAME"
echo "Port:         $PORT"
echo ""
echo "Step 1: On your LOCAL machine, run:"
echo ""
echo "    ssh -N -L 8080:${HOSTNAME}:$PORT <username>@wi-hpc"
echo ""
echo "Step 2: Open your browser to:"
echo ""
echo "    http://localhost:8080"
echo ""
echo "To stop the session, cancel the job:"
echo "    scancel <job-id>"
echo "==========================================="

# Keep the script running (wait for background job)
wait

Step 2: Submit the job

sbatch launch-code-server.sh

This returns a Job ID (e.g., 12345). Check the output file to see the connection instructions:

cat code-server-12345.out

You'll see something like:

===========================================
code-server is running!

Compute Node: node042
Port:         8723

Step 1: On your LOCAL machine, run:

    ssh -N -L 8080:node042:8723 username@wi-hpc

Step 2: Open your browser to:

    http://localhost:8080

To stop the session, cancel the job:
    scancel 12345
===========================================

Step 3: Create the SSH tunnel (on your local machine)

Copy the SSH command from the output file and run it in a new terminal on your local machine:

ssh -N -L 8080:node042:8723 username@wi-hpc

Replace the following:

  • node042 with the actual compute node name from the output
  • 8723 with the actual port from the output
  • username with your cluster username
  • wi-hpc with your cluster's hostname (e.g., wi-hpc.wistar.org)

The SSH tunnel will run in the foreground. Keep this terminal open — as long as it's running, your connection is active. You'll see no output; this is normal.

Step 4: Open code-server in your browser

Once the SSH tunnel is active, open your browser and navigate to http://localhost:8080

You should see the VSCode editor. You're now connected!

Step 5: Stop the session

When you're done:

  1. Close your browser tab (optional; code-server will clean up when the job ends)
  2. Stop the SSH tunnel by pressing Ctrl+C in the terminal where you ran the ssh -N -L ... command
  3. Cancel the SLURM job (recommended to free resources):
scancel <job-id>

Where <job-id> is the number from sbatch (e.g., 12345).

Interactive Launch (For Testing)

Best for: Quick testing, debugging, short sessions (< 1 hour).

If you prefer to test without creating a file, you can launch interactively using srun:

Step 1: Request resources and start code-server

srun --pty --partition=defq --cpus-per-task=2 --mem=4GB --time=01:00:00 /bin/bash

Once you have a shell on the compute node, load the module and start code-server:

module load code-server/1.105.1
PORT=$(shuf -i 8000-9999 -n 1)
HOSTNAME=$(hostname)

echo "Starting code-server on $HOSTNAME:$PORT"
code-server --auth none --bind-addr 0.0.0.0:$PORT

Step 2: Note your connection details

The code-server output will show something like:

[2025-11-11T10:30:45.123Z] info  code-server 1.105.1
[2025-11-11T10:30:45.456Z] info  HTTP server listening on http://127.0.0.1:8723

The port shown here may differ from $PORT if the port was already in use. Always check the output to confirm the actual port.

Step 3: In a new terminal on your local machine, create the SSH tunnel

ssh -N -L 8080:<node-hostname>:<actual-port> <username>@wi-hpc

Step 4: Open in your browser

Once the tunnel is active, open http://localhost:8080 in your browser to access code-server.

Step 5: Stop code-server

In the terminal on the compute node (where code-server is running), press Ctrl+C to stop it. The shell will exit and your resources will be freed.

Use tmux for better session management

Consider wrapping your interactive session in tmux to keep it alive even if your SSH connection drops.

srun --pty --partition=defq --cpus-per-task=2 --mem=4GB /bin/bash
tmux new-session -s vscode
module load code-server
# ... start code-server ...

Reconnect with:

ssh -N -L 8080:<node>:<port> <user>@wi-hpc

Troubleshooting

Port already in use

If you get an error like "Address already in use," the port you selected is occupied. This is rare with shuf but can happen:

  • For batch jobs: Check the job output file; the script will report the actual port used.
  • For interactive sessions: Pick a different port manually: PORT=8500 instead of shuf.

SSH tunnel not connecting

If ssh -N -L ... hangs or refuses to connect:

  • Verify the compute node hostname is correct (check the job output or hostname command).
  • Verify the port is correct (especially if the code-server process picked a different port).
  • Check that you can SSH to the cluster: ssh username@wi-hpc.
  • If using a VPN, ensure it is active and you have access to the cluster's internal network.

Browser shows "Connection Refused"

If you see this error when navigating to http://localhost:8080:

  • Verify the SSH tunnel is running (you should see your terminal blocked, no output).
  • Verify code-server started successfully on the compute node (check the job output or interactive terminal).
  • Try closing and reopening the browser tab.
  • Check the job error file for errors: cat code-server-<job-id>.err.

Module not found

If module load code-server fails:

  • Ask your cluster administrator to install code-server or verify the module name.
  • List available modules: module avail | grep code.

Additional Resources