Getting Started with VS Code Remote-SSH: Connect, Forward Ports, and Trust Your Workspace

When you need to edit code, run builds, or debug on a machine you don’t have locally—perhaps a cloud VM or a lab server—you face a choice: install a full IDE on the remote host or work entirely through a thin client. VS Code Remote‑SSH offers a middle ground: the familiar VS Code UI stays on your laptop, while the heavy lifting (file system, runtimes, extensions) happens on the remote machine over an SSH tunnel.

How Remote‑SSH Splits the Workload

The extension consists of two parts:

• Local UI – runs on your workstation and renders the editor, menus, and any extensions that contribute only to the user interface (themes, keybindings, etc.).
• Remote Server – a copy of the VS Code Server that is downloaded into ~/.vscode-server on the remote host the first time you connect. This server hosts the extension host, language services, debuggers, and any extensions that need access to the remote filesystem or APIs.

Authentication is delegated to your system’s SSH client and agent; VS Code never reads or stores your private key.

Connecting and Verifying the Setup

1. Open the Command Palette (Ctrl+Shift+P) and run Remote-SSH: Connect to Host….
2. Select or add an SSH host (e.g., [contact removed]). VS Code will invoke ssh with your existing config.
3. After the connection succeeds, the window title changes to something like [SSH: remote.example.com] Folder: /home/myuser/project.
4. To confirm the server is in place, open a terminal (Ctrl+`) and run:

   ls -la ~/.vscode-server/bin

   You should see a directory named after a version hash containing the server binaries and a subfolder extensions where remote‑side extensions are installed.

Practical Example: Forwarding a Remote Service

Suppose the remote host runs a web application on port 8080 that you want to reach from your browser locally.

1. In VS Code, open the PORTS pane (bottom panel).
2. Click Forward a Port, enter the remote port 8080, and set the local port to the same value (or another free port like 3000).
3. VS Code creates an SSH tunnel: localhost:<local-port> → remotehost:<remote-port>.
4. Verify the tunnel by running locally:

   curl -I http://localhost:8080

   You should receive the HTTP headers from the remote service.

Port forwarding rules can also be declared permanently in .vscode/settings.json:

{
  "remote.forwardPorts": [8080]
}

Workspace Trust and Limitations

Remote folders are treated as untrusted until you explicitly grant trust. This blocks automatic tasks, debuggers, and certain extension contributions that could execute arbitrary code. To trust a folder:

1. When you first open a remote folder, a notification appears: “You trust the authors of the files in this folder?”.
2. Click Trust Folder or run Manage Workspace Trust: Trust Workspace from the Command Palette.

Even with trust, keep in mind these constraints:

• Extensions that rely on local GUI APIs (e.g., screen‑capture, native hardware access) may not work because they execute in the remote server context.
• High‑latency links can make file search, large explorer views, and terminal typing feel sluggish.
• The initial connection may take tens of seconds to minutes while the server downloads over SSH, especially on narrow bandwidth links.

Actionable Checklist

1. Ensure you can SSH to the target host from your local terminal (ssh [contact removed]).
2. Start the Remote‑SSH connection from VS Code and verify the [SSH: …] window title.
3. Check ~/.vscode-server on the remote host for the server binary and extensions.
4. If you need to reach a service, add a port forward in the PORTS panel or via settings.json and test with curl or your browser.
5. Trust the workspace when prompted, or manually enable it via the Command Palette.

By understanding the split‑architecture, verifying the server installation, configuring port forwarding, and applying workspace trust, you can develop on remote machines with the same VS Code experience you enjoy locally—while staying aware of the trade‑offs that come with remote execution.