Connect SSH and VS Code

Start with a running allocation#

Ask your research client to call research_allocate, then follow research_job until it is Running. Request enough CPU, memory and time for your editor and workload. Add GPUs if your experiment needs them. Desktop connections use the same workspace and Slurm resource limits.

1. 01

   Install standard tools

   Use OpenSSH and upstream wstunnel 11.0.0. For an editor, install VS Code and Microsoft’s Remote - SSH extension. The download from Matilda contains plain configuration, a pinned host key and an expiring credential.

2. 02

   Prepare an Ed25519 key

   Use an existing Ed25519 key or generate a dedicated one below. Keep the private file on your computer; paste only its public .pub file into the site.

3. 03

   Download SSH setup

   Open the connection_url returned by research_allocate or research_job and sign in with the same research account. Choose macOS, Windows or Linux, enter your public key and the desktop path to its private key, then choose Download SSH setup.

mkdir -p ~/.ssh
ssh-keygen -t ed25519 -f ~/.ssh/matilda_ed25519
cat ~/.ssh/matilda_ed25519.pub

New-Item -ItemType Directory -Force "$HOME/.ssh" | Out-Null
ssh-keygen -t ed25519 -f "$HOME/.ssh/matilda_ed25519"
Get-Content "$HOME/.ssh/matilda_ed25519.pub"

View full screenshot

Install wstunnel once#

wstunnel is an independent open-source tool. Install it through your normal package manager or the official erebe/wstunnel GitHub releases. These instructions are verified with version 11.0.0. OpenSSH is normally included on macOS and Linux; Windows provides an OpenSSH Client optional feature.

brew install wstunnel
wstunnel --version

# If you already use Scoop:
scoop install wstunnel
wstunnel --version

# Alternatively, download the Windows release for your architecture from:
# https://github.com/erebe/wstunnel/releases/tag/v11.0.0
# Extract wstunnel.exe into a folder on your user PATH.
# Open a new terminal and restart VS Code after updating PATH.

# Choose the official binary for your architecture.
case "$(uname -m)" in
  x86_64) matilda_arch=amd64; matilda_sha=9708a99717b5a951453c2ff7c14c25d3418d02ca7fcb96fdb382a8f2083bab5e ;;
  aarch64|arm64) matilda_arch=arm64; matilda_sha=b86abf73e340ed0c3ff9a77a5458aa27213784920ec65513132b36def45edc94 ;;
  *) printf 'Choose your architecture from the official wstunnel releases.\n'; exit 1 ;;
esac
matilda_tmp=$(mktemp -d)
mkdir -p "$HOME/.local/bin"
curl -fL "https://github.com/erebe/wstunnel/releases/download/v11.0.0/wstunnel_11.0.0_linux_${matilda_arch}.tar.gz" -o "$matilda_tmp/wstunnel.tar.gz"
printf '%s  %s\n' "$matilda_sha" "$matilda_tmp/wstunnel.tar.gz" | sha256sum -c -
tar -xzf "$matilda_tmp/wstunnel.tar.gz" -C "$HOME/.local/bin" wstunnel
chmod 755 "$HOME/.local/bin/wstunnel"
rm -rf "$matilda_tmp"
export PATH="$HOME/.local/bin:$PATH"
wstunnel --version
# Add ~/.local/bin to your shell profile's PATH for future sessions.

Extract your SSH setup#

The ZIP contains four text files: an SSH .conf, a .known_hosts entry, an authentication .headers file and README.txt. Extract them into ~/.matilda/ssh on the computer where you run SSH. Add the Include line at the top of your existing SSH config so these allocation settings are selected before general Host * settings.

# Replace ALLOCATION with the identifier in your downloaded ZIP filename.
mkdir -p ~/.matilda/ssh ~/.ssh
unzip -o ~/Downloads/matilda-ALLOCATION.ssh.zip -d ~/.matilda/ssh
chmod 700 ~/.matilda/ssh
chmod 600 ~/.matilda/ssh/*
touch ~/.ssh/config
if ! grep -qxF 'Include ~/.matilda/ssh/*.conf' ~/.ssh/config; then
  matilda_config=$(mktemp "$HOME/.ssh/config.matilda.XXXXXX")
  { printf '%s\n' 'Include ~/.matilda/ssh/*.conf'; cat ~/.ssh/config; } > "$matilda_config"
  mv "$matilda_config" ~/.ssh/config
fi
chmod 600 ~/.ssh/config
ssh matilda-ALLOCATION

# Replace ALLOCATION with the identifier in your downloaded ZIP filename.
$matildaRoot = Join-Path $env:USERPROFILE ".matilda/ssh"
New-Item -ItemType Directory -Force $matildaRoot | Out-Null
Expand-Archive -Path "$HOME/Downloads/matilda-ALLOCATION.ssh.zip" -DestinationPath $matildaRoot -Force
New-Item -ItemType Directory -Force "$HOME/.ssh" | Out-Null
$matildaConfig = Join-Path $env:USERPROFILE ".ssh/config"
$matildaInclude = "Include ~/.matilda/ssh/*.conf"
$matildaPrevious = if (Test-Path $matildaConfig) { [IO.File]::ReadAllText($matildaConfig) } else { "" }
if (($matildaPrevious -split '\r?\n') -notcontains $matildaInclude) {
  [IO.File]::WriteAllText($matildaConfig, $matildaInclude + "`n" + $matildaPrevious, [Text.UTF8Encoding]::new($false))
}
ssh matilda-ALLOCATION

The private key path you entered must match the public key registered in the site. Your host is matilda- followed by the allocation identifier. Its shell starts in /workspace. If you previously used the Python connector for this allocation, extracting the new setup replaces its configuration while keeping the same host alias.

Open your workspace in VS Code#

1. 01

   Download VS Code Server locally

   Add the setting below to your desktop VS Code settings. VS Code downloads its server on your computer and transfers it to the allocation, whose external networking is isolated.

2. 02

   Connect to the allocation host

   Open the Command Palette, choose Remote-SSH: Connect to Host and select the matilda-… alias from your downloaded setup. Choose Linux if asked, regardless of your desktop operating system.

3. 03

   Open /workspace

   Choose File → Open Folder and enter /workspace. The integrated terminal, VS Code Server and remote extensions run inside your allocation. The same files are available through your researcher client’s workspace tools.

{
  "remote.SSH.localServerDownload": "always"
}

Allow a few minutes for the first server installation. Server files and extensions consume your workspace quota and allocation memory. Upload and download throughput through the gateway is paced at 2 MiB/s per connection. Internet-enabled allocations can fetch extensions and packages over public HTTPS. Use matilda-venv for a persistent project environment with the prepared training stack.

Connections to the same allocation share its private network, allowing the editor to reconnect to its running server. Closing the editor does not cancel the allocation; cancel unused allocations with research_cancel_job.

View full screenshot

Transfer files and open a local service#

Use the same host alias with scp or sftp to move inputs and results within your workspace quota. Replace matilda-ALLOCATION below with your actual alias. Transfers and forwarded ports use the existing HTTPS gateway.

scp dataset.csv matilda-ALLOCATION:/workspace/dataset.csv
scp matilda-ALLOCATION:/workspace/results.json ./results.json
sftp matilda-ALLOCATION

ssh -L 127.0.0.1:8888:127.0.0.1:8888 matilda-ALLOCATION
# Start your service on 127.0.0.1:8888 inside this allocation.
# Open http://127.0.0.1:8888 on your desktop.

Forwarded destinations are limited to localhost inside your own allocation. Your SSH session gives access to that allocation and its workspace; infrastructure services remain private.

Find a way forward#

For an unresolved issue, send your administrator the allocation identifier, UTC time, desktop operating system, wstunnel version and visible error. Keep your setup archive, .headers file and private key private.