Navigation :

VSCode and Cursor

Using SSH with VSCode and Cursor

Support scope: Our support for VSCode is limited. If SSH works outside of VSCode but the settings below don’t resolve your issue, we will suggest a clean reinstall.

VSCode and Cursor are used interchangeably in this documentation unless otherwise noted.

VSCode and Cursor connect to remote systems using the “Remote - SSH” extension. This extension must be installed before proceeding.

Quick Start

Install the Remote - SSH extension

Open VSCode or Cursor
From the left sidebar, select Extensions
Search for “Remote - SSH” and install it

Configure your SSH client

If using Linux or macOS, set up the CSAIL SSH configuration and optionally CSAIL Kerberos for passwordless access.

Windows users can proceed directly to the next section.

VSCode and Cursor on Windows do not support SSH control sockets, so connections cannot be shared. You may need to complete Duo authentication more frequently than on Linux or macOS.

Required Settings

Open VSCode user settings and search for “Remote.SSH”. Configure these settings:

Lockfiles in Tmp: Set to true (required for VSCode with AFS home directories)

Server Install Path: Add an entry for each CSAIL server you connect to:

Item: The server hostname (e.g., servername.csail.mit.edu)
Value: /tmp/.vscode.username or /tmp/.cursor.username (e.g., /tmp/.vscode.acloss)

You MUST set Server Install Path correctly for ALL hosts you connect to, or VSCode will not work properly.

Show Login Terminal: Set to true

Use Local Server: Set to true

Connect to a Server

Use the command palette (Ctrl-Shift-P or Cmd-Shift-P) and select “Remote-SSH: Connect to Host”. Enter the full hostname: username@servername.csail.mit.edu. Complete Duo authentication when prompted in the terminal at the bottom of the screen.

Troubleshooting

Clear the VSCode server

If you experience unexplained behavior:

Close all VSCode/Cursor windows
Use the command palette to run “Remote-SSH: Kill VS Code Server on Host”
Alternatively, SSH to the server in a terminal and run: ps ux | grep .vscode-server | awk '{print $2}' | xargs kill

Issues with AFS home directories

VSCode creates a .vscode-server directory that requires creating lockfiles. AFS home directories may not support this.

Solution: Ensure “Lockfiles in Tmp” is set to true and configure Server Install Path to a non-AFS location (see Required Settings above).

Performance issues

If VSCode appears slow or hangs, this may be due to .vscode-server indexing a large number of files in AFS. You can delete the .vscode-server directory as a temporary fix, but performance issues may recur if using AFS storage.

Clean reinstall

If the above steps don’t resolve the issue, perform a clean reinstall by deleting all VSCode user data:

Windows: Delete %APPDATA%\Code and %USERPROFILE%\.vscode
macOS: Delete $HOME/Library/Application Support/Code and ~/.vscode
Linux: Delete $HOME/.config/Code and ~/.vscode

Then reinstall VSCode or Cursor.

Advanced Information

Lockfiles and .vscode-server

When connecting remotely, VSCode creates a .vscode-server directory in your home directory and uses lockfiles to coordinate access. If your home directory is on AFS, VSCode cannot create lockfiles there and will fail with what may appear to be an authentication error. Setting “Lockfiles in Tmp” to true works around this issue.

If you must use AFS storage, configure Server Install Path to point to a temporary directory instead of your home directory.

Remote execution and process persistence

When you connect using Remote-SSH, VSCode starts a node process on the remote system that persists after you disconnect. This can affect features that depend on login events, such as AFS token refresh and group membership updates. If something works once but fails on a new connection, this is likely the cause.

Server Install Path configuration

Use the command palette to access “Remote-SSH: Settings” to configure Server Install Path on a per-host basis. Set the Item to the full hostname (including .csail.mit.edu) and the Value to the desired directory path.

Do not set Server Install Path to /tmp, /scratch, or other shared directories. Use a directory unique to your username.

Opening the SSH config file

Use the command palette to run “Remote-SSH: Open Configuration File” to edit your SSH configuration directly (e.g., to set up aliases or jump host settings).

For additional help, contact TIG at help@csail.mit.edu.