Downloads
Sign In

Sign in to Teleport

Teleport Cloud LoginLogin to your Teleport AccountDashboard LoginLegacy Login & Teleport Enterprise Downloads
Get Started
Fork me on GitHub

Teleport

Remote Development With Visual Studio Code

Version 14.x
  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

This guide explains how to use Teleport and Visual Studio Code's remote SSH extension.

Prerequisites

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.0.1.

    See Installation for details.

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

    You can download these tools from the Cloud Downloads page.

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.0.1.

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
Note

Linux and MacOS clients should rely on their operating system-provided OpenSSH packages. Windows 10 clients should refer to Microsoft's OpenSSH guide; older clients can use ssh.exe from either Git for Windows or Microsoft's Win32-OpenSSH project.

  • Update the variables below with your environment's information to use our example commands directly.

Step 1/3. First-time setup

Configure your local SSH client to access Teleport Nodes. Replace teleport.example.com with the address of your Teleport Proxy Service (e.g., mytenant.teleport.sh for Teleport Cloud users), and replace alice with your Teleport user.

log in to your proxy:
tsh login --proxy teleport.example.com --user alice

generate the OpenSSH config for the proxy:
tsh config --proxy teleport.example.com

Append the resulting configuration snippet into your SSH config file located in the path below:

$HOME/.ssh/config

%UserProfile%\.ssh\config

Warning

If using PowerShell on Windows to write your SSH config, note that normal shell redirection may write the file with the incorrect encoding. To ensure it's written properly, try the following:

tsh.exe config | out-file .ssh\config -encoding utf8 -append

You should be able to connect to the desired node using following command, replacing user with the username you would like to assume on the node.

ssh user@example-node.teleport.example.com

The SSH config you generated earlier instructs your SSH client to run tsh proxy ssh to access a Node in your Teleport cluster. However, running an ssh command against the Teleport Proxy Service at yourtenant.teleport.sh will result in an error.

Note

Teleport's certificates expire fairly quickly, after which SSH attempts will fail with an error like the following:

[email protected]: Permission denied (publickey).
ERROR: exit status 255

kex_exchange_identification: Connection closed by remote host

When you see this error, re-run tsh login to refresh your local certificate.

Step 2/3. Configure Visual Studio Code

Install the Remote - SSH extension in your local VS Code instance. A new "Window Indicator" (icon with two arrows) should appear in the bottom left of your VS Code window.

Window Indicator in bottom left corner of VS Code
Window Indicator

Prior to connecting with a host, set the Remote.SSH: Use Local Server setting to false in the extension setting. You can search for @ext:ms-vscode-remote.remote-ssh to find the plugin-specific settings.

VSCode Setting

To connect, click on the icon with two arrows and select "Connect to Host...". Select "+ Add New SSH Host..."

For each host you wish to remotely develop on, add an entry like the following:

Adding new Node

When prompted to choose which SSH Configuration file to update select the one we generated during Step 1.

This will write a new node into your SSH Configuration file. You can edit and manage all your nodes in this file.

Step 3/3. Start a Remote Development session

Start a Remote Development session by either:

  1. Clicking "Connect" on the notification that opens after adding a new host.
Notification of "Host added" that has connect button
Host added notification
  1. Clicking on the Window Indicator again and selecting "Connect to Host". You should see the host you just added and any others in your Configuration file in the drop down.
Connect to a Node

On first connect, you'll be prompted to configure the remote OS. Select the proper platform and VS Code will install its server-side component. When it completes, you should be left with a working editor:

VS Code connected to a Teleport Node
Connected VS Code

The Window Indicator in the bottom left highlights the currently connected remote host.

Next Steps

Connecting to OpenSSH Hosts

It's possible to remotely develop on any OpenSSH host joined to a Teleport cluster so long as its host OS is supported by VS Code. Refer to the OpenSSH guide to configure the remote host to authenticate via Teleport certificates, after which the procedure outlined above can be used to connect to the host in VS Code.

Using OpenSSH clients

This guide makes use of tsh config; refer to the dedicated guide for additional information.

Further reading