Prepare Local Machine

Before you can start working on your project in a remote dev environment, you should prepare your local machine. Some steps are optional as they depend on your setup, such as the Git authentication method, the IDE you use, etc. Skip the steps that aren't relevant to you.

Install JetBrains Gateway

JetBrains Gateway is a desktop application that connects you to your remote development environment.

Download and install the Gateway app for your operating system.
Launch the app.

Add SSH key to Git hosting server

If your Git server uses the SSH protocol, you need to generate an SSH key pair and add the public key to the Git hosting service. Your local machine will use the private key to authenticate with the Git server.

Generate an SSH key pair if you don't have one:
ssh-keygen -t ed25519
As a result, you will get two files, for example, mykey (a private key) and mykey.pub (a public key).
Copy the public key to the clipboard and add it to your Git hosting service. For example:
- GitHub
  Open your profile settings, go to SSH and GPG keys, and click New SSH key. Paste the public key into the Key field and click Add SSH key.
  For details, see the GitHub documentation
- GitLab
  Open your profile Preferences, go to SSH keys, and click Add new key. Paste the public key into the Key field and click Add key.
  For details, see the GitLab documentation
- Bitbucket
  Open your Personal Bitbucket settings. Under Security, open SSH keys and click Add key. Paste the public key into the Key field and click Add key.
  For details, see the Bitbucket documentation

(Windows only) Enable SSH agent

You need an SSH agent running on your local machine in the following cases:

(Optional) Authentication to a Git server via SSH agent
To work with a Git repository from a dev environment, you need to authenticate yourself to the Git server. If the Git server uses the SSH protocol, you can either provide your private SSH key to the IDE directly or provide the key to the SSH agent and then forward the agent to the dev environment.
SSH connection to a dev environment
To connect to a dev environment using the SSH protocol, you need the SSH agent running on your local machine.
VS Code remote development
To work with a dev environment in VS Code, you need to connect to the VS Code server running on the dev environment using the SSH protocol. To establish the connection, you need the SSH agent running on your local machine.

On Linux and macOS, the SSH agent is pre-installed. On Windows 10 and 11, you can use the pre-installed OpenSSH client, but you will need to enable the SSH agent.

(Windows) To enable the SSH agent

Open the Windows Start menu, type Services, and press Enter.
In the Services window, find the OpenSSH Authentication Agent service.
Right-click the service and select Properties.
In the Properties window, set the Startup type to Automatic.
Click Start to start the service, then click OK.

Prepare SSH agent

You should prepare your local SSH agent in the following cases:

SSH connection to a dev environment
To connect to a dev environment using the SSH protocol, you need the SSH agent running on your local machine. To establish the connection, you need to provide CodeCanvas with your public key and add your private SSH key to the SSH agent.
VS Code remote development
To work with VS Code dev environments, CodeCanvas uses the SSH protocol. Namely, it connects to the VS Code server with the SSH agent running on your local machine. To establish the connection, you need to provide CodeCanvas with your public key and add your private SSH key to the SSH agent.

Generate an SSH key pair if you don't have one:
ssh-keygen -t ed25519
As a result, you will get two files, for example, mykey (a private key) and mykey.pub (a public key).
Copy the public key to the clipboard and add it to CodeCanvas:
1. In the top right corner, click your name and select Profile.
2. In the sidebar menu, select SSH Keys.
3. Click Add SSH Key.
4. Paste the public key into the Key field, add a description, and click Add.
On your local machine, add your private SSH key to the SSH agent:
ssh-add ~/.ssh/mykey
Replace ~/.ssh/mykey with the actual path to your private key.
You should get a message like Identity added: ~/.ssh/mykey.
If you use a password manager to store your SSH keys, configure the SSH_AUTH_SOCK environment variable. It should point to the SSH agent socket provided by your password manager. For example, for 1Password, follow their SSH client configuration guide.

Last modified: 28 August 2024