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 New Gitpod Workspace with VS Code Desktop • Gitpod Dashboard

Open VS Code Desktop from VS Code Browser

Start a new Gitpod workspace
Open the command palette ( CtrlCmd + Shift + P )
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

Navigate to your Gitpod preferences
Select “VS Code” (without the browser label)
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 (SSH)

The three main methods granting VS Code Desktop access to your workspace are:

SSH Gateway access using an uploaded public SSH key (recommended)
SSH Gateway access using the owner token
Using Local Companion (legacy)

See configure SSH for more on SSH Gateway.

Important: You must first ensure that gitpod.remote.useLocalApp is set to false in your VS Code user preferences for Gitpod to connect via the two SSH Gateway methods.

Connect to VS Code Desktop using an uploaded public SSH key

First, VS Code Desktop will check if you have already added a public SSH key to Gitpod and that the associated private key is available on your device.

If you haven’t set up an SSH key with Gitpod, you can go to gitpod.io/keys to upload a public key. Alternatively, you can continue using the owner token approach detailed below.

The VS Code Desktop prompt from Gitpod when opening a workspace with no SSH key found locally or uploaded to Gitpod.

You must have at least one public key uploaded to Gitpod, and a matching private key locally on your device to avoid this prompt. VS Code Desktop will look to find private keys in the following named files within the .ssh directory listed under your home directory.

id_dsa
id_dsa
id_ecdsa
id_rsa
id_ed25519
id_xmss
id_ecdsa_sk
id_ed25519_sk

Connect to VS Code Desktop using the workspace owner token

If you cannot upload a public key to Gitpod (for whatever reason) selecting Copy will allow you to proceed to access your Gitpod workspace using the owner token approach. Selecting Copy will copy the necessary password to your clipboard to be pasted in the subsequent password prompt.

VS Code prompting for a password. This message is shown when the public key warning notice is dismissed on the previous page by selecting Copy.

Note: Gitpod previously required a local private SSH key to be stored in the default SSH directory, otherwise Gitpod would prompt for a “password”. This limitation is no longer required. If not using an SSH uploaded key, you may be prompted for a password (the owner token), or asked for the passphrase associated with your SSH key.

Connect to VS Code Desktop using Local Companion (Legacy)

If VS Code Desktop cannot connect directly via the SSH Gateway methods described above, the Local Companion approach is used as a fallback to tunnel your SSH connection. Gitpod via the VS Code Desktop plugin will download and start the Local Companion process on your behalf.

This approach is not recommended because:

It overwrites your remote.SSH.configFile VS Code setting.
Downloads and starts Local Companion in a non-transparent way.
Is less performant than the SSH Gateway approach.

If required, you manually can force VS Code Desktop to always fallback to the Local Companion by setting the property gitpod.remote.useLocalApp in your user preferences to true.

The VS Code Desktop Gitpod extension “useLocalApp” setting

Deprecation Notice: The fallback SSH connection using Local Companion for VS Code Desktop will be deprecated in a future release of Gitpod. If you cannot connect to your workspaces directly via SSH, for example, because your firewall is blocking the SSH connection, please contact support with troubleshooting logs.

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

You can optionally enable Settings Sync with Gitpod to keep your extensions, themes and settings up-to-date with VS Code Browser and Desktop. See VS Code settings sync for more

Enable Settings Sync with Gitpod

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:

Download the desired font to your local machine and install it locally on your operating system.
Open the editor’s user settings (e.g. File > Preferences > Settings > User)
Configure your font with the editor.fontFamily setting:
language:
json
```
{
  "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.

FAQs

When opening VS Code Desktop, the owner token wasn’t copied to my clipboard, where can I find it?

When opening VS Code Desktop, if you are being prompted for the owner token password, but cannot copy it to clipboard, you can find the password on the gitpod workspaces page under “connect via SSH”.

The password prompt in VS Code Desktop for the owner token

Accessing the owner token string manually from the Gitpod dashboard

Note: Pattern of the owner token is: user#password@host

How do I know whether I’m connecting to VS Code Desktop via Local Companion or SSH Gateway?

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.

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

Resolver error: Error: Got bad result from install script

I’m being prompted for a password/passphrase but VS Code Desktop cannot authenticate?

The owner token prompt and passphrase prompt in VS Code Desktop can look similar, however require different inputs. If you’re seeing a failure to connect it could be you are using the incorrect authentication method, e.g. pasting an owner token for a passphrase, or vice versa.

Owner token - If the password prompt in VS Code Desktop asks Enter password for workspace@\*.gitpod.io, this prompt is for the owner token of the workspace, not the passphrase associated with your SSH key.

The password prompt in VS Code Desktop for the owner token

Accessing the owner token string manually from the Gitpod dashboard

SSH key Passphrase - If your SSH key has a “passphrase” associated with the SSH key (it is not required for SSH keys), you’ll need to enter your passphrase. If your public key has no passphrase, you should not see the passphrase prompt.

Passphrase prompt from VS Code requiring the SSH key passphrase

Note: If you cannot remember your passphrase, consider creating a new SSH key and uploading the new key to Gitpod.

How do I enable SSH agent forwarding for Desktop VSCode?

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.)

Upload Files from local to VS Code Desktop

Troubleshooting

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

Checking your Gitpod VS Code Desktop extension version is using the latest version.
Attempt to directly connect via SSH using the -v to show verbose SSH logs. For example: ssh -v workspacename@hostname. You can find the ssh command in the workspace list on your Gitpod dashboard, see the command-line docs for more.
If you’re a self-hosted customer, ensure SSH Gateway is configured correctly.

If you are still experiencing issues using VS Code Desktop and Gitpod, please contact support with any related troubleshooting logs