VS Code on HPC Compute Node

Quick Start

# 1. Create the startup script
cat > ~/start_jupyter.sh << 'EOF'
#!/bin/bash
find_available_port() {
    local port
    for port in {8888..8988}; do
        if ! ss -tuln | grep -q ":$port "; then
            echo $port
            return 0
        fi
    done
    echo "No available ports found" >&2
    return 1
}
PORT=$(find_available_port)
if [ -z "$PORT" ]; then
    echo "Error: Could not find available port"
    exit 1
fi
rm -rf ~/.local/share/jupyter/runtime/kernel-*.json 2>/dev/null
echo "=========================================="
echo "Starting 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
EOF

# 2. Make it executable
chmod +x ~/start_jupyter.sh

# 3. Request compute node and start Jupyter
srun --constraint=“Replace with available nodes” mem=12G —pty bash
./start_jupyter.sh

Then in VS Code:

1. Forward the port shown in output
2. Connect notebook to http://localhost:PORT/lab?token=...

Detailed Setup

Step 1: Create the Startup Script

Create a script start_jupyter.sh in your home directory with the following content:

#!/bin/bash

# Find an available port between 8888-8988
find_available_port() {
    local port
    for port in {8888..8988}; do
        if ! ss -tuln | grep -q ":$port "; then
            echo $port
            return 0
        fi
    done
    echo "No available ports found" >&2
    return 1
}

# Get available port
PORT=$(find_available_port)

if [ -z "$PORT" ]; then
    echo "Error: Could not find available port"
    exit 1
fi

# Clean up old kernel state to prevent "kernel does not exist" errors
rm -rf ~/.local/share/jupyter/runtime/kernel-*.json 2>/dev/null

echo "=========================================="
echo "Starting Jupyter Lab on port $PORT"
echo "=========================================="

# Start Jupyter with token authentication and VS Code compatibility
jupyter lab --no-browser --ip=0.0.0.0 --port=$PORT \
    --ServerApp.allow_origin='*' \
    --ServerApp.allow_remote_access=True \
    --ServerApp.disable_check_xsrf=True

Make the script executable:

chmod +x ~/start_jupyter.sh

Step 2: Connect to HPC via VS Code Remote-SSH

To recap what was documented previously:

1. Open VS Code
2. Press F1 or Ctrl+Shift+P (Windows/Linux) / Cmd+Shift+P (Mac)
3. Type “Remote-SSH: Connect to Host”
4. Select your HPC login node from the list or enter connection details

Step 3: Request a Compute Node

Open a terminal in VS Code and run:

srun --constraint=<Replace with available nodes types> mem=12G —pty bash

Verify you’re on a compute node:

hostname  # Should show compute-node-XXX, not login node

Step 4: Start Jupyter Lab

./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 entire URL with token!**

Step 5: Forward the Port in VS Code

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

Step 6: Connect Your Notebook to Jupyter

1. Open your .ipynb file in VS Code
2. Click “Select Kernel” in the top-right corner
3. Choose “Existing Jupyter Server”
4. Select “Enter the URL of the running Jupyter server”
5. Paste the URL, replacing 127.0.0.1 with localhost:

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

6. Press Enter

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

Important Best Practices

• Clean up when you finish the analysis even before the job expires: scancel <job_id>