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

OpenSource
Version 9.0
Improve

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 one of our Getting Started guides.

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

    tctl version
    Teleport v9.2.3 go1.17
    tsh version
    Teleport v9.2.3 go1.17

    See Installation for details.

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

  • The tctl admin tool and tsh client tool version >= 9.2.3, which you can download by visiting the customer portal.

    tctl version
    Teleport v9.2.3 go1.17
    tsh version
    Teleport v9.2.3 go1.17

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 9.1.2. To download these tools, visit the Downloads page.

    tctl version
    Teleport v9.1.2 go1.17
    tsh version
    Teleport v9.1.2 go1.17
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.

Step 1/3. First-time setup

Configure your local SSH client to access Teleport Nodes, assigning the --proxy flag to the address of your Teleport Proxy Service (e.g., mytenant.teleport.sh for Teleport Cloud users).

log in to your proxy:
tsh login --proxy proxy.foo.example.com --user alice
generate the OpenSSH config for the proxy:
tsh config --proxy proxy.foo.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 [email protected][node name].[cluster name]

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

Warning

Due to a VS Code bug, you can not use Remote - SSH UI to add SSH hosts. It will improperly rewrite the quoting in tsh config's generated configuration. If your SSH configuration becomes corrupted, re-run tsh config.

Install the Remote - SSH extension in your local VS Code instance. A new "Remote Explorer" sidebar entry should appear.

Select it, ensure "SSH Targets" is selected in the drop-down menu, and select the "Configure" gear icon:

VS Code sidebar with the Remote Explorer pane open and Configure highlighted

VS code will prompt you for your SSH config file.

Select the one we generated during Step 1 and open it in the editor.

Warning

Do not use VS Code's SSH config helper. If prompted for an SSH command, close the dialog and select the "Configure" icon instead.

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

Host node000.foo.example.com
    User alice

When finished, save the file. If the added host doesn't automatically appear in the list, select the Refresh button.

Step 3/3. Start a Remote Development session

Start a Remote Development session by right-clicking on any host added above and selecting either "Connect to..." option:

Connecting to a Teleport host in VS Code

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

The status 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, added in Teleport 7.0; refer to the dedicated guide for additional information.

Manually configure an OpenSSH client to use the VS Code's remote SSH extension with older Teleport clients.

Further reading

Have a suggestion or can’t find something?
IMPROVE THE DOCS