Skip to main content
This guide shows how to use Cursor (a fork of Visual Studio Code) to develop on a remote machine over SSH. This workflow is ideal when your development machine (laptop, macOS, or Windows) is different from the remote host (for example, a Linux server with a GPU). Using the Remote - SSH flow, Cursor runs the editor UI locally while executing terminals, debuggers, and processes on the remote host. Cursor supports Windows, macOS, and Linux. The Remote - SSH extension used here is the same extension available for Visual Studio Code, so the workflow will feel familiar if you’ve used VS Code remotely. Ensure the Remote - SSH extension is available in your Cursor extensions list.
A screenshot of Visual Studio Code showing the Extensions view open to the "Remote - SSH" extension page, with details, install/disable buttons, and a preview of using VS Code to connect to a remote server. The left sidebar lists other remote-related extensions and the right pane shows marketplace metadata.
Aside from Remote - SSH, Cursor also supports Dev Containers and other remote extensions. Choose the remote method that best fits your workflow — e.g., Dev Containers for reproducible dev environments, Remote - SSH for direct access to a specific host.
Example workload to run remotely
  • Below is a simple Python example (SVM cross-validation) that demonstrates a CPU/GPU-bound task you might run on a remote machine.
Add a new SSH host
  1. In Cursor, select “Connect via SSH”.
  2. Choose “Add New SSH Host” and enter the host using the form user@host (recommended) or the IP address.
If you only provide an IP address, Cursor/VS Code will append your local username to the entry which can cause accidental logins as the wrong user — so prefer user@host. When prompted, choose where to save the SSH configuration entry (your local SSH config file).
Always prefer specifying user@host in your SSH entries (for example jeremy@10.0.0.94). If you only specify an IP, your local username may be appended automatically and you may log in as a different user than intended.
A dark-themed app window showing a prompt to select an SSH configuration file (highlighting a local .ssh/config path). The main area displays a "Cursor" welcome screen with buttons for Open project, Clone repo, and Connect via SSH.
Connecting and selecting the remote platform
  • After adding the host, click Connect. Cursor opens a new window and prompts you to select the remote platform (Linux, Windows, or macOS) for that host.
  • You will typically confirm the host fingerprint and then authenticate with a password or SSH key.
A dark-themed application start screen for "Cursor" showing a large mouse cursor icon above three buttons labeled "Open project", "Clone repo", and "New Window." At the top is a dropdown prompting selection of the remote host platform (Linux, Windows, macOS) for host "10.0.0.94."
Typical prompts you will see from the client (example)
Setting up the remote server
  • If this is the first time connecting, Cursor/VS Code will install the VS Code server on the remote host. You’ll see a status such as “Downloading VS Code Server…” while installation completes.
  • After installation, the server runs on the remote machine and accepts connections from the Cursor client.
A dark-themed Visual Studio Code window showing a startup screen labeled "Cursor" with buttons to open a project, clone a repo, or open a new window. The left sidebar has an "Open Folder" button and the bottom status area shows "Downloading VS Code Server...".
Open a remote folder or clone a repository
  • Once the server is running, open a folder that exists on the remote host or clone a repository into the remote workspace.
  • The Cursor file explorer now reflects files on the remote filesystem.
Example: listing a projects folder on the remote host
Open files and run terminals on the remote host
  • Any terminal you open from a Cursor window connected to the host runs on the remote machine.
  • Editing files, running scripts, installing packages, or debugging will execute remotely, using the remote host’s CPU/GPU and filesystem.
Example: remote terminal and process listing
Example snippet from a remote project (Flask application)
  • You can open and edit apps like a Flask project directly on the remote host. Below is a small excerpt.
Connecting to other hosts and operating systems
  • You can add multiple SSH host entries to your SSH config and switch between machines (Linux, macOS, Windows).
  • The process is the same: add user@host to your SSH config, connect from Cursor, choose the correct platform, and authenticate.
Example macOS connection prompt
Quick reference: remote development workflow Recommended links and references Summary
  • Cursor uses the Remote - SSH model to run development workflows on a remote host while displaying the editor UI locally.
  • Editing, terminals, debugging, and package management operate on the remote machine.
  • Always specify user@host in your SSH entries to avoid unintended username substitutions.
  • Use SSH keys for repeatable, passwordless authentication.
If you plan to use multiple remote hosts frequently, save each host entry in your SSH config with descriptive comments and enable SSH key authentication to avoid repeated password prompts.

Watch Video