VS Code Desktop
With VS Code Desktop Support, you keep your local editor configurations1 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
- Start a new Gitpod workspace
- Open the command palette ( )
- Type “Open in VS Code” and hit
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 tofalse
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:jsonlanguage:
{ "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:
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.)
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 thessh
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