Secure Shell Protocol (SSH) is the basis for connecting to your Gitpod workspace when using VS Code Desktop, JetBrains Gateway, or accessing via the command-line from a local machine. See command-line editors & IDEs documentation for more.

​
Manage your SSH Keys

​
Installing a supported SSH client

How to install a local SSH client depending on your operating system.
OSInstructions
Windows 10 1803+ / Server 2016/2019 1803+Install the Windows OpenSSH Client.
Earlier WindowsInstall Git for Windows.
macOSComes pre-installed.
Debian / Ubuntu / MintRun sudo apt-get install openssh-client
RHEL / Fedora / CentOSRun sudo yum install openssh-clients
Arch / ManjaroComes pre-installed.
PuTTY for Windows is not a supported client

​
Create an SSH key

Check to see if you already have an SSH key on your local machine. The key is typically located at ~/.ssh/id_ed25519.pub on macOS / Linux, and the .ssh directory in your user profile folder on Windows (for example C:\Users\your-user\.ssh\id_ed25519.pub). If you do not have a key, run the following command in a local terminal / PowerShell to generate an SSH key pair: 
ssh-keygen -t ed25519
You will then be prompted to enter a secure passphrase, but you can leave that blank. You should now have a id_ed25519.pub file which contains your new public SSH key.
If you are using a legacy system that doesn’t support the Ed25519 algorithm, you can use rsa instead: ssh-keygen -t rsa -b 4096
Don’t have ssh-keygen? Install a supported SSH client.

​
SSH file and folder permissions

macOS / Linux: On your local machine, make sure the following permissions are set:
Folder / FilePermissions
.ssh in your user folderchmod 700 ~/.ssh
.ssh/config in your user folderchmod 600 ~/.ssh/config
.ssh/id_ed25519.pub in your user folderchmod 600 ~/.ssh/id_ed25519.pub
Any other key filechmod 600 /path/to/key/file
Windows: The specific expected permissions can vary depending on the exact SSH implementation you are using. We recommend using the out of box Windows 10 OpenSSH Client. In this case, make sure that all of the files in the .ssh folder for your remote user on the SSH host is owned by you and no other user has permissions to access it. See the Windows OpenSSH wiki for details. For all other clients, consult your client’s documentation for what the implementation expects.

​
Upload an SSH key to Gitpod

Once you’ve created an SSH key pair, you can upload your public SSH key to Gitpod, by navigating to gitpod.io/keys where you can upload one or more public SSH keys.

SSH page of the Gitpod dashboard

Paste your public key, and give your key a memorable title so that you can remember the name of the public key later if you choose to add multiple keys, e.g. “Gitpod Bastion Host SSH Key”

Adding an SSH Key to Gitpod

​
Edit an SSH key in Gitpod

Gitpod doesn’t support editing an SSH key. To update an SSH key, delete the key and re-upload the SSH key to Gitpod.

​
Delete an SSH key from Gitpod

To delete an SSH key, click the kebab menu to the right of the SSH key in the dashboard and select “delete”.

Deleting an SSH key from Gitpod

​
SSH Gateway

SSH Gateway facilitates connection via SSH for direct SSH access using uploaded public keys, and using the workspace owner token. Both the VS Code Desktop and JetBrains integrations use SSH Gateway to connect to Gitpod workspaces.

​
What is SSH Gateway?

SSH Gateway is an intermediary service within Gitpod that proxies incoming SSH requests to the appropriate running workspaces.

SSH Gateway architecture in Gitpod

​
SSH Gateway in Self-Hosted

If you are running a Self-Hosted Gitpod installation, you will need to ensure that:
  1. The installation has the SSH Gateway component configured and deployed
  2. Your networking and firewalls are configured to allow SSH traffic via port 22.
See the Self-Hosted Reference Architectures for more.

​
Troubleshooting

VS Code Desktop and SSH explained blog has a bunch of good troubleshooting notes, you may check them out.

​
unix_listener: path “/somewhere/xyz” too long for Unix domain socket

  • Open your SSH config file in a text editor. (i.e. ~/.ssh/config or /etc/ssh/ssh_config[1])
  • Append the following to it:
Host *.gitpod.io
     ControlPath /tmp/%r-gitpod
  • Save the file.
  • Now try connecting via SSH or VS Code Desktop again.