> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/integrations/tempest-remote-vscode.md).

# Tempest Remote — Open Saved SSH Servers in VS Code

Connect Visual Studio Code to saved Tempest SSH servers with Tempest Remote, the local Tempest CLI and Microsoft Remote - SSH.

**Tempest Remote** opens your saved SSH connections in Visual Studio Code. Pick a server and a remote directory, then use remote files, terminals, extensions and debugging through Microsoft Remote - SSH.

The extension uses **Tempest CLI** for accounts, credentials, SSH authentication, proxies and jump hosts. The Tempest desktop app does not need to stay open. The CLI command is **`tempest remote`**.

## Requirements

* VS Code 1.85 or later on macOS, Windows or Linux.
* Microsoft's [Remote - SSH extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
* A Tempest CLI build that includes `tempest remote control` and `tempest remote pipe`.
* A signed-in Tempest account with saved SSH servers, a verified `portForwarding` entitlement, and a vault policy that permits TCP forwarding.
* A remote SSH server supported by Remote - SSH, where your SSH user can install and run VS Code Server.

Check the installed CLI commands:

```bash
tempest --version
tempest remote --help
```

The `remote` help must list both `control` and `pipe`. The extension also checks that control reports `protocol: 1`. Update the CLI and extension together.

## Install

Download **Tempest CLI** from [gotempest.app/download](https://gotempest.app/download), selecting your platform, and put the executable on your `PATH`. See [Tempest CLI](/cli/tempest-cli.md) for account and installation details.

Install **Tempest Remote** and **Remote - SSH** in your **local** VS Code. The extension's Marketplace identity is `AltasExpressLLC.tempest-remote` and its display name is **Tempest Remote**. Until a Marketplace listing is published, install a supplied VSIX:

1. Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux).
2. Run **Extensions: Install from VSIX...**.
3. Select the Tempest Remote `.vsix` file.
4. Reload the window if requested.

Opening the extension source directory is not an installation. F5 loads it in an **Extension Development Host**; that alone does not make it available in ordinary VS Code windows.

## Sign in and select an account

Sign in through the Tempest app, or use:

```bash
tempest login
tempest account list
```

The desktop app and CLI share the local account and vault root. Save your SSH servers in Tempest before connecting; check them with `tempest ssh list`.

When there are several accounts, `tempest account use <ID|EMAIL>` selects the default account. The extension uses the CLI's selected account. It does not currently have a separate account picker.

## Connect

1. Click VS Code's remote indicator in the bottom-left corner.
2. Choose **Tempest: Connect to Server**. The same command is available in the Command Palette.
3. Select a saved SSH server.
4. Enter an absolute remote folder path, for example `/home/alice/project`.
5. Complete any authentication prompts.

Loading servers and connecting show progress notifications in VS Code. Use **Cancel** to stop a pending connection and retry.

VS Code opens a new remote window. Remote - SSH may ask you to choose the remote operating system and installs or starts VS Code Server.

Open a terminal in that window and check `hostname` and `pwd` to confirm the host and directory. The new window provides the remote file explorer, terminal and debugger.

## Authentication prompts

| Prompt                                     | VS Code interaction                                            |
| ------------------------------------------ | -------------------------------------------------------------- |
| Vault password or SSH password             | Hidden input box.                                              |
| Private-key passphrase or security-key PIN | Hidden input box.                                              |
| Keyboard-interactive challenge / OTP       | Input box; echo follows the server's prompt.                   |
| New or changed SSH host key                | Explicit confirmation showing host, key type and fingerprint.  |
| Security-key signing                       | Confirmation followed by the physical authenticator operation. |

Cancel a prompt to stop authentication. Compare a new or changed fingerprint with a trusted source before accepting it. Initial vault/password setup must be completed in Tempest first.

## Settings and lifecycle

| Setting                                 | Use                                                                 |
| --------------------------------------- | ------------------------------------------------------------------- |
| `tempest.cliPath`                       | Local CLI executable name or absolute path. Default: `tempest`.     |
| `remote.SSH.configFile`                 | Optional custom SSH config. Tempest adds its managed Include there. |
| `remote.SSH.remoteServerListenOnSocket` | Keep disabled; this version supports TCP mode.                      |

Use **Tempest: Open Settings** to open the CLI path setting directly in the graphical Settings editor. Its default is `tempest` from PATH; editing settings.json is not required.

The CLI manages local connection files in **`~/.tempest/remotes/`** and preserves existing user SSH host entries.

Control handles authentication and establishes the upstream tunnel. Remote - SSH starts a Tempest **ProxyCommand**, which attaches to that control by session ID and carries SSH data. Closing the original local window after opening a remote window does not disconnect an attached session.

When the last SSH pipe closes, control releases the tunnel and exits after a **three-second reconnect grace**. Setup without an attached pipe expires after **120 seconds**. On macOS/Linux, SIGHUP, SIGINT and SIGTERM sent to a proxy are passed to control for that pipe; if it was the last pipe, control closes the tunnel immediately. Other attached pipes remain usable. Terminating control itself closes all of its pipes.

Reopening a recent remote folder ensures its saved server again. After a dropped upstream connection, reconnect or reopen the remote window; interrupted commands are not automatically replayed.

## Troubleshooting

### No Tempest entry in the remote menu

Make sure **Tempest Remote** is installed and enabled in the current local VS Code profile. Reload the window after installing or updating. A development window referencing an old source path must be restarted with the current project directory.

### CLI cannot start, or remote protocol is unavailable

Set `tempest.cliPath` to an absolute path and run `tempest remote --help` with that exact executable. The extension requires `tempest remote control --protocol 1`, plus `tempest remote pipe`. Update the CLI together with the extension if attach support is missing.

### portForwarding entitlement was not verified

Force a server refresh before retrying:

```bash
tempest account list --refresh
```

This waits for fresh account information and entitlements instead of returning as soon as cached credentials unlock the vault. A refresh failure is reported, and displayed cached values may remain stale.

Check the selected account, verified entitlement and vault TCP-forwarding policy. A displayed plan name alone does not establish that the required feature grant was verified.

### SSH config or local key preparation fails

Check write access to the Tempest directory and effective SSH config. Make sure `ssh-keygen` is available locally.

### Remote - SSH fails after Tempest setup

Open **View → Output**:

* **Tempest Remote** shows request results, safe error codes and connection failure reasons.
* **Remote - SSH** shows VS Code Server bootstrap and connection details.

Authentication answers, passwords and private keys are not written to the Tempest Remote output channel. Failure notifications do not hold the connection command's lock; you can retry without first dismissing an old notification.

## Current scope

Supported: saved SSH connections, prompts, proxies/jump hosts, remote command execution, PTY/resizing, stdout/stderr, exit status and the TCP forwarding used by Remote - SSH.

Unix-domain socket mode, remote port forwarding, SFTP subsystem requests, X11 and SSH agent forwarding through this local service are outside the current scope. Mosh and saved terminal startup commands do not apply to remote development.

The extension is **MIT licensed**. Tempest CLI, the desktop app and services have separate licenses and subscription terms.

## See also

* [Build your own integration — remote control protocol v1](/integrations/tempest-remote-plugin-protocol.md)
* [Accounts and vaults](/accounts-vaults-and-privacy/accounts-and-vaults.md)
* [SSH port forwarding](/connections-and-ssh/ssh-port-forwarding.md)