Access via VSCode-based IDEs

VSCode is the most popular IDE with a rich set of features and extensions that go far beyond what is currently possible in the JupyterLab interface. It also supports different tools that use LLMs and agentic frameworks for code completion, generation and debugging; some of them available as VSCode extensions (e.g. GitHub Copilot, OpenAI Codex), and others as standalone IDEs (e.g. Cursor, Antigravity) built on top of VSCode.

Purdue AF allows to connect to your AF session from any VSCode-based IDE and take advantage of these features. Please follow the instructions below; you will only need to run steps 1-6 once, and then you will be able to connect using instructions from step 7, as long as you have an AF session running.

1. Install Remote-SSH extension in your IDE

  1. In VSCode/Cursor/Antigravity, click on the Extensions icon in the left sidebar.

  2. Search for Remote - SSH extension by Microsoft or Anysphere and install it.

2. Install websocat command on your local machine

  1. Check if you have websocat command on your local machine: which websocat. If the output of this command is not empty, skip this step.

  2. Install websocat on your local machine.

    On Linux, run the following commands:

    sudo wget -qO /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl
sudo chmod a+x /usr/local/bin/websocat

    On macOS, run the following command:

    brew install websocat

    Once installed, check if the command is available: which websocat.

    On Windows:

3. Configure SSH keys on local machine

  1. You may already have the SSH key pair generated: look for ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub files on your local machine.

  2. If you do not have the key pair yet, you can follow the GitHub SSH key instructions and reuse the generated key pair for Purdue AF.

  3. Add the following host entry to ~/.ssh/config on your local machine:

    Host PurdueAF
    HostName cms.geddes.rcac.purdue.edu
    User USERNAME
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    ProxyCommand websocat --binary -H="Authorization: token TOKEN" asyncstdio: wss://%h/user/USERNAME/sshd/

  4. If you are on Windows, make two small changes to the entry above: * Replace websocat with full path to websocat.exe from the previous step. * Replace asyncstdio: with stdio:

  5. Replace USERNAME (in two places!) with your Purdue AF username:

    • If you are using Purdue account, this is your Purdue Career accountusername.

    • If you are using CERN account, this is your CERN username followed by -cern.

    • If you are using FNAL account, this is your FNAL username followed by -fnal.

You will also need to replace TOKEN with the JupyterHub token that you will obtain in the next step.

4. Start a Purdue AF session and obtain a JupyterHub token

  1. In your web browser, open Purdue AF and log in.

  2. Select CPU, RAM, and GPU resources and start the session.

  3. Once the session is started, in the JupyterLab menu, go to File -> Hub Control Panel.

  4. Click the Token tab.

  5. Click Request new API token.

  6. Copy the token string and use it to replace TOKEN in the ~/.ssh/config file.

5. Configure SSH access on the Purdue AF side

This is the last step that we need to enable your AF session to authorize connections from your local machine.

On your local machine, run this to copy your public key to the clipboard:

On Linux:

cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

On macOS:

cat ~/.ssh/id_ed25519.pub | pbcopy

On Windows:

type %USERPROFILE%\.ssh\id_ed25519.pub | clip
- OR, if using Git Bash or other shell -
cat ~/.ssh/id_ed25519.pub | clip

On the AF session, run the following commands one by one. When the cat command prompts for input, paste your public key (Ctrl-V) and press Ctrl-D to finish:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
cat >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

6. Verify home directory permissions on AF side

Your home directory must have exactly the following permissions:

$ ls -ld ~/
drwxr-xr-x <username> ... ... ... /home/<username>/

If the permissions are different, run chmod 755 ~/ to fix them.

7. Connect from your IDE

  1. In your IDE (VSCode, Cursor, etc.), open the command palette (usually Ctrl-Shift-P or Cmd-Shift-P).

  2. Search for Remote-SSH: Connect to Host... command and select it.

  3. Select PurdueAF from the host list. A new IDE window will open, connected to your AF session.

  4. Open a folder on the AF filesystem once the connection is established. It can be any folder in your home directory, or other directory you have access to (e.g. /depot/cms/users/<username>/, /work/users/<username>/, etc.).

  5. Success! Now you can use your local IDE to browse and edit files in the AF. LLM-powered tools will also have access to your remote files, so you can use them to generate and debug code, but always be careful not to let them run dangerous commands, e.g. deleting important files.

8. Install extensions on the AF side (optional)

After the connection succeeds, you can install extensions on the remote VSCode server that now runs on the AF side. To do that, simply open the Extensions tab in the window connected to the AF.

Warning

The Jupyter extension which allows to run remote notebooks from your local IDE is not going to work, as it cannot properly discover the AF kernels just yet. We are working on this functionality and will announce it when it is available.

Troubleshooting

If connection fails, you can usually extract useful informantion from the IDE console.

Some known caveats are:

  • Your AF home directory must NOT be group-writable for SSH keys to work. Check it with ls -ld /home/<username>/ and make sure the group permissions do not include w.

  • If you see errors like websocat: command not found, check that websocat command is available on your local machine: which websocat. If it is not available, you need to install websocat; if it is available but you are still seeing the same error, change the ProxyCommand in the ~/.ssh/config file to use the full path to the websocat binary (for example /opt/homebrew/bin/websocat).