VS Code Desktop

With VS Code Desktop Support, you keep your local editor configurations¹ and benefit from Gitpod’s high-spec servers & automated prebuilds. As usual, your code executes in an ephemeral Gitpod workspace, keeping each of your projects isolated from one another.

Open a workspace in VS Code Desktop

There are currently three supported ways to open a VS Code Desktop session connected to a Gitpod workspace, either by opening it from the Gitpod dashboard, choosing VS Code Desktop as your default preference, or directly from within VS Code Browser itself.

Open VS Code Desktop from the Gitpod Dashboard

You can start a workspace with VS Code Desktop directly from Gitpod Dashboard. You can do that from by clicking on the New Workspace button. Then, you can select the context url, Editor and custom workspace class.

Open VS Code Desktop from VS Code Browser

1. Start a new Gitpod workspace
2. Open the command palette ( F1 or CtrlCmd + Shift + P )
3. Type “Open in VS Code” and hit Enter

You will now be redirected to VS Code Desktop.

Open VS Code via the Command Palette

Open VS Code Desktop using your preferences

1. Navigate to your Gitpod preferences
2. Select “VS Code” (without the browser label)
3. Restart any running workspaces

When the workspace starts, you will be prompted to open VS Code Desktop. You can also access your workspace using VS Code Browser, or copy SSH credentials from this page.

Open VS Code Desktop from the workspace start page

Selecting VS Code Desktop as an editor preference

Connecting to VS Code Desktop

Connection to VS Code Desktop works via a secure tunnel established on the users device. A minor update is required to the users SSH configuration. A directory is created ~/.ssh/code_gitpod.d, and an Include statement is added to the main SSH configuration file (~/.ssh/config). No other SSH configuration files are read, or written to by Gitpod.

SSH configuration modifications

The following shows examples of the changes Gitpod makes to a user’s SSH configuration files to establish a connection to Gitpod.

language: 

bash

copy code

copied successfully

$ cat ~/.ssh/code_gitpod.d/config
### This file is managed by Gitpod. Any manual changes will be lost.

Host *.vss.gitpod.io
  ...

Caption: An example of the directory created ~/.ssh/code_gitpod.d and included configuration in the auto-generated ~/.ssh/code_gitpod.d/config file.

language: 

bash

copy code

copied successfully

$ cat ~/.ssh/config
## START GITPOD INTEGRATION
## This section is managed by Gitpod. Any manual changes will be lost.
Include "code_gitpod.d/config"
## END GITPOD INTEGRATION

Caption: Example of the update to the SSH config file in ~/.ssh/config.

How VS Code Desktop establishes connection to Gitpod

Legacy Connection Methods

For documentation on previous / deprecated methods of connecting to VS Code see Legacy - VS Code Desktop Connection Methods, this includes:

1. SSH Gateway access using an uploaded public SSH key
2. SSH Gateway access using the owner token
3. Using Local Companion

Reconnect to VS Code Desktop

When VS Code Desktop disconnects from the workspace, either you are experiencing genuine connectivity issues, or it’s possible that the workspace has timed out and stopped.

VS Code Desktop attempting to reconnect

To restart the workspace, click Open Workspace from the workspace start page or from the dashboard and VS Code Desktop should automatically reconnect.

Please note: There is currently no way to start a workspace directly from VS Code Desktop.

The open workspace button shown on a stopped workspace page

VS Code settings sync

For enabling Setting Sync in VS Code Desktop please refer to the official VS Code Settings Sync documentation

Notice: Syncing between VS Code Browser and VS Code Desktop is not supported.

Managing VS Code extensions

VS Code runs extensions in one of two places: locally on the UI / client side, or remotely on your Gitpod workspace.

For further details, please refer to the official VS Code docs on how to manage extensions.

Custom fonts in VS Code Desktop

The process of installing fonts matches how you typically install custom fonts locally:

1. Download the desired font to your local machine and install it locally on your operating system.
2. Open the editor’s user settings (e.g. File > Preferences > Settings > User)
3. Configure your font with the editor.fontFamily setting:
   language: 

   json

   copy code

   copied successfully

   {
   	"editor.fontFamily": "Your custom font name"
   }

Optimizing VS Code Desktop

If you’re using VS Code Desktop for frequent work you’ll want to optimize your setup. Below are some tips to get a workspace set up as efficient as possible.

SSH fingerprint

Accepting the SSH fingerprint in VS Code

It is common convention to be asked for a fingerprint when accessing a new SSH server. When the fingerprint is accepted, a reference to the server is stored in your local known_hosts file, which suppresses subsequent SSH connection prompts for that server.

You should only be presented with a request to trust the Gitpod workspace when using the legacy Local Companion approach of connecting to VS Code Desktop.

By swapping to the SSH Gateway approach of accessing VS Code Desktop, your known hosts file will be updated automatically. See connecting to VS Code Desktop for more.

Workspace Trust

The VS Code Workspace Trust popup

Workspace Trust is a feature within VS Code implemented to help prevent automatic code execution by disabling or limiting the operation of several VS Code features: tasks, debugging, workspace settings, and extensions.

When opening a Gitpod workspace with VS Code Desktop for the first time you will be prompted by a trust modal (given that you have not disabled the workspace trust setting in VS Code).

Selecting ”Yes, I trust the authors” will open the workspace and store a reference to the workspace host and directory. Opening the same workspace will not show the prompt again. However, due to a hostname change, new workspaces require trust to be accepted on first open.

Choosing ”No, I do not trust the authors” will enter you into the VS Code Restricted Mode. You can edit code in your workspace, but some features will be restricted. You can disable the VS Code Restricted Mode after the initial prompt.

If required, you can disable the workspace trust feature, however this is not recommended. Select ”Manage Workspace Trust” from the Manage gear menu to view and modify your VS Code Workspace Trust settings.

Updating Workspace Trust settings

See Workspace Trust in the VS Code official documentation for more.

How do I know how I’m connecting to VS Code Desktop?

If you’re unsure whether you’re connecting via the local companion, or SSH Gateway approach, when connected to your Gitpod workspace, VS Code Desktop will show the connection host in the bottom left.

• Local SSH - SSH: <workspaceid>.vss.gitpod.io or SSH: <workspaceid>.vsi.gitpod.io
• SSH Gateway - SSH: <workspaceid>.ssh.*.gitpod.io
• Local Companion: <workspaceid> (no domain)

The SSH host information shown in the bottom left of VS Code Desktop

I’m being asked to choose the platform of the remote host. What should I choose?

When connecting, sometimes VS Code Desktop fails to automatically detect the host OS of a Gitpod workspace, asking the following: Select the platform of the remote host "{id}".

No matter what the OS is on your computer, you should always choose Linux as the remote host platform, since this is the operating system all Gitpod workspaces run on.

If you choose another option, you may encounter an error like this:

language: 

text

copy code

copied successfully

Resolver error: Error: Got bad result from install script

How do I enable SSH agent forwarding for Desktop VS Code?

Gitpod extension delegates ssh connection to the MS Remote - SSH extension so agent forwarding should just work if you configure it in your ~/.ssh/config file:

Host *.gitpod.io
    ForwardAgent yes

Upload Files

You can upload files to your workspace by dragging and dropping them into the editor. This method works with every IDE (e.g. Intellij, PyCharm, etc.)

Troubleshooting

If you are still having issues connecting to VS Code Desktop from Gitpod, try:

1. Check if your VS Code Desktop application and Gitpod VS Code Desktop extension version are all using the latest version.
2. Identify which method you’re using to connect to Gitpod, if it’s SSH Gateway or Local Companion see their troubleshooting here
3. If it’s Local SSH, please export log on the failed to connect window and email us