> 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-sdk.md).

# Tempest Remote SDK

Use the open-source Node.js SDK to integrate saved Tempest SSH servers with editors, terminals and automation through Tempest CLI remote protocol v1.

[Tempest Remote SDK](https://github.com/tempest-term/tempest-remote-sdk) is an **MIT-licensed Node.js library** for the local Tempest CLI remote-control protocol. It provides the shared control client used by [Tempest Remote for VS Code](https://github.com/tempest-term/tempest-remote-editors/tree/main/vscode) and the Tempest Codex plugin. Build another integration by supplying your own server picker, authentication UI and SSH consumer.

The SDK is the npm package **`@tempest-term/remote-sdk`**. It requires Node.js 18+ and a separately installed Tempest CLI supporting both `tempest remote control` and `tempest remote pipe`. The SDK does not contain the CLI binary, SSH credentials, or an SSH implementation. The Tempest desktop app need not stay open.

## Install

The package is hosted on **GitHub Packages**. Configure the scope in `.npmrc`:

```ini
@tempest-term:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```

Use a GitHub token with `read:packages` as `NODE_AUTH_TOKEN`. GitHub Actions consumers can use `GITHUB_TOKEN` with `packages: read` after their repository is granted package Actions access. Public npm packages on GitHub also require authentication. Built VSIX/Codex artifacts bundle the SDK, so end users do not need registry credentials.

Once a version has been published:

```sh
npm install @tempest-term/remote-sdk
```

Before the initial npm release, install from the [GitHub repository](https://github.com/tempest-term/tempest-remote-sdk), pinned to a commit, or use a tarball created by `npm pack`. Consumers can then switch to a registry version without changing their `require('@tempest-term/remote-sdk')` imports.

## Connect a saved server

In an async integration handler:

```js
const { ControlClient } = require('@tempest-term/remote-sdk');

const control = new ControlClient('tempest', async prompt => {
  if (prompt.kind === 'password') return ui.hiddenInput(prompt.message);
  if (prompt.kind === 'text') return ui.textInput(prompt.message);
  if (prompt.kind === 'confirm') return ui.confirm(prompt.message);
  return undefined;
});

try {
  const servers = await control.listServers();
  const selected = await ui.pickServer(servers);
  if (!selected) return;
  const { sshHost } = await control.ensureRemote(selected.id);
  await editor.openSshFolder(sshHost, '/home/alice/project');
} finally {
  control.dispose();
}
```

`ui` and `editor` are your host-specific adapters. TypeScript declarations and CommonJS/ESM imports are included. The SDK has no runtime npm dependencies.

`listServers()` checks protocol v1 and validates the server list. `ensureRemote(serverId, { configFile? })` checks protocol v1, prepares or reuses the CLI-owned tunnel, and validates the returned `sshHost` and `sessionId`. Saved-server IDs are opaque: pass them intact. The lower-level `request(method, params)` interface remains available.

An optional constructor `account` selects one CLI account for that process. The SDK does not change the account selected in the desktop app. Login and initial vault setup happen through Tempest CLI or the Tempest app.

## Authentication and lifecycle

The host must display prompts locally. Return strings for password/text, booleans for confirmation, or `undefined` to cancel. Hide secret input, show the complete host-key/security-key prompt, and let the user decide. Never log answers or automatically accept host keys. The SDK bounds frames, correlates requests, serializes prompts, applies finite timeouts and sanitizes CLI errors.

After successful setup, `dispose()` closes control stdin and releases the process without killing the tunnel. Before setup succeeds, it cancels that setup process. `cancel()` explicitly terminates this client's setup process.

Your editor or OpenSSH must attach through the generated SSH alias within 120 seconds. Once attached, SSH pipes drive the tunnel's lifetime. A temporary SSH keepalive can bridge a longer interactive setup. Re-run `ensureRemote` before opening an expired saved connection; an alias alone cannot restart it.

CLI owns credentials, jump hosts, SSH keys, config and tunnel state. The SDK does not read private descriptors or carry SSH data in its control channel. For custom `configFile`, the consumer must use that same effective SSH config.

## SDK, plugins and MCP

* **SDK:** reusable Node.js control client for `tempest remote control`.
* **VS Code extension:** SDK plus native server/authentication UI and Microsoft Remote - SSH folder opening.
* **Codex plugin:** SDK plus local terminal authentication, an SSH keepalive, and a Codex add-host link. The user connects and selects a remote folder in Codex; the link does not automatically create/open a project.
* **Tempest MCP:** a separate CLI entry point, `tempest mcp`, registered by the Codex plugin over stdio. It provides AI terminal tools, not the desktop application's remote-project transport.

The SDK repository includes cross-platform CI, npm package/type checks and a tag-triggered GitHub Packages publishing workflow using `GITHUB_TOKEN` with `packages: write`. No npmjs account is required; adding the workflow alone does not publish a package.

## See also

* [Remote integration protocol v1](https://docs.gotempest.app/integrations/tempest-remote-plugin-protocol.md)
* [Tempest Remote for VS Code](https://docs.gotempest.app/integrations/tempest-remote-editors.md#vs-code)
* [Tempest CLI](https://docs.gotempest.app/cli/tempest-cli.md)
* [Tempest MCP](https://docs.gotempest.app/ai-and-automation/install-tempest-mcp-server-in-ai-clients.md)

## More clients

The [Remote Editors integration](https://github.com/tempest-term/tempest-remote-editors) bundles this SDK for JetBrains, Zed, Cursor and command-line SSH tools. Cursor also has its own VSIX built from the VS Code source. [Claude Code](https://docs.gotempest.app/integrations/tempest-remote-editors.md#claude-code) and [Codex](https://docs.gotempest.app/integrations/tempest-remote-editors.md#codex) package the SDK alongside their skills. Native client bootstrap must be tested separately from SDK transport checks.
