From 5e1c3b8b63ffa28783a35d04d44ee6f7d8d07c18 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Fri, 1 May 2026 01:12:52 +0000 Subject: [PATCH 1/6] docs: Document Warp's SSH extension and feature support over SSH Update the SSH and SSH-feature-support docs to reflect the new SSH extension that enables file tree, native file reads, native code diffs, and reliable multiplexed completions over SSH on macOS and Linux. Reframe tmux Warpification as the fallback path. Embed Kevin's Loom demo on the SSH page, refresh adjacent caveats in code/agent docs to narrow the sed/grep fallback scope, and add a 2026.04.29 changelog entry. Co-Authored-By: Oz --- .../capabilities/codebase-context.mdx | 15 ++-- src/content/docs/changelog/index.mdx | 15 ++++ .../docs/code/code-editor/file-tree.mdx | 4 + .../code-editor/language-server-protocol.mdx | 2 +- src/content/docs/code/code-review.mdx | 4 + src/content/docs/code/overview.mdx | 4 +- src/content/docs/code/ssh-feature-support.mdx | 34 ++++++--- src/content/docs/terminal/warpify/index.mdx | 2 +- src/content/docs/terminal/warpify/ssh.mdx | 74 +++++++++++++------ 9 files changed, 110 insertions(+), 44 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx index 2bd8488..f09f98f 100644 --- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx +++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx @@ -38,12 +38,15 @@ When you open a directory in Warp, we check if it is part of a Git repository. I Code indexed with Codebase Context is never stored on our servers. Codebase Context works with both local agent sessions and [cloud agent runs](/agent-platform/cloud-agents/overview/). Without Codebase Context enabled, agents will still be able use terminal commands (i.e. `grep`, `sed`) to navigate your code. ::: -:::danger -**Codebase Context doesn't work within SSH or WSL sessions.** \ -\ -Feature requests for support are being tracked in the following GitHub issues: \ -\- SSH: [https://github.com/warpdotdev/Warp/issues/6831](https://github.com/warpdotdev/Warp/issues/6831)\ -\- WSL: [https://github.com/warpdotdev/Warp/issues/6744](https://github.com/warpdotdev/Warp/issues/6744) +:::caution +**Codebase Context doesn't work in SSH or WSL sessions yet.** + +Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) already enables the file tree, native file reads, and native code diffs over SSH on macOS and Linux, and Codebase Context is on the SSH roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. + +Feature requests: + +* SSH: [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831) +* WSL: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744) ::: ![Codebase indexing settings in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.](../../../../assets/agent-platform/codebase-context-main.png) diff --git a/src/content/docs/changelog/index.mdx b/src/content/docs/changelog/index.mdx index c49dd13..9d2a190 100644 --- a/src/content/docs/changelog/index.mdx +++ b/src/content/docs/changelog/index.mdx @@ -7,6 +7,21 @@ description: >- Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) +### 2026.04.29 (v0.2026.04.29.08.45) + +**New features** + +* \[Preview] Warp's new **SSH extension** brings the local Warp experience to remote macOS and Linux hosts. On first connect, choose **Install Warp's SSH extension** to enable a real file tree backed by the remote filesystem and have the coding agent apply edits via Warp's native diff tool instead of `sed`. Choose **Continue without installing** to fall back to the existing tmux-powered Warpification path. See [SSH with Warp features](/terminal/warpify/ssh/) and [Feature support over SSH](/code/ssh-feature-support/). + +**Improvements** + +* \[Preview] Completions and autosuggestions over SSH are now multiplexed through the SSH extension over a single connection. This eliminates the remote host's `MaxSessions` ceiling, lets generators run in parallel, and removes the occasional errors that the previous per-command SSH session approach injected into blocks. +* Added the `warpify.ssh.ssh_extension_install_mode` setting (`always_ask`, `always_install`, `never_install`) under **Settings** > **Features** > **Warpify** to control how the SSH extension install prompt behaves. See [All settings reference](/terminal/settings/all-settings/#ssh). + +:::note +Code Review, LSP, and Codebase Context support over SSH are still in progress and will land in subsequent Preview releases. +::: + ### 2026.04.22 (v0.2026.04.22.08.46) **New features** diff --git a/src/content/docs/code/code-editor/file-tree.mdx b/src/content/docs/code/code-editor/file-tree.mdx index 263d4d1..6ebcf5f 100644 --- a/src/content/docs/code/code-editor/file-tree.mdx +++ b/src/content/docs/code/code-editor/file-tree.mdx @@ -9,6 +9,10 @@ description: >- Warp includes a **native file tree** that makes it easy to explore and manage project files. The file tree is available whenever in any directory and it automatically reflects your project structure as files are added, removed, or changed. +:::note +The file tree also works over SSH on macOS and Linux when Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) is installed on the remote host. +::: + ### Opening the file tree You can open the file tree from the tools panel on the left hand side: diff --git a/src/content/docs/code/code-editor/language-server-protocol.mdx b/src/content/docs/code/code-editor/language-server-protocol.mdx index 952f38b..35fca7b 100644 --- a/src/content/docs/code/code-editor/language-server-protocol.mdx +++ b/src/content/docs/code/code-editor/language-server-protocol.mdx @@ -82,7 +82,7 @@ LSP features stay in sync across [shared buffers](/code/code-editor/#shared-buff ## Limitations -* **Local sessions only** - LSP is not available over SSH or WSL sessions. These are tracked in GitHub issues [#6831](https://github.com/warpdotdev/Warp/issues/6831) (SSH) and [#6744](https://github.com/warpdotdev/Warp/issues/6744) (WSL). +* **Local sessions only** - LSP is not yet available over SSH or WSL sessions; SSH support is on the roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. Tracked in GitHub issues [#6831](https://github.com/warpdotdev/Warp/issues/6831) (SSH) and [#6744](https://github.com/warpdotdev/Warp/issues/6744) (WSL). * **One server per language** - Each language maps to a single server (for example, Rust always uses `rust-analyzer`). Custom server configurations are not yet supported. * **Project-scoped** - Language servers operate at the Git repository root level. Files outside a repository may not receive LSP features. * **Server availability** - Some features (like formatting) depend on the specific language server's capabilities. Not all servers support all features. diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx index 4f4a6bb..057eacf 100644 --- a/src/content/docs/code/code-review.mdx +++ b/src/content/docs/code/code-review.mdx @@ -9,6 +9,10 @@ import VideoEmbed from '@components/VideoEmbed.astro'; ## Overview +:::note +The Code Review panel is currently local-only and is on the [SSH](/code/ssh-feature-support/) roadmap. +::: + When you are working locally in a Git repository with uncommitted changes, the **Code Review panel** lets you inspect, edit, and manage code changes directly inside Warp. It integrates with Git and Warp's Agents, giving you the ability to: * Review diffs and attach them as context for the Agent diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx index 3b93faf..91cd406 100644 --- a/src/content/docs/code/overview.mdx +++ b/src/content/docs/code/overview.mdx @@ -7,7 +7,7 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; :::note -Several coding features — including Codebase Context, code diffs, the code editor, and the file tree — are not yet available in SSH or WSL sessions. +On macOS and Linux SSH sessions, Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. Codebase Context, Code Review, and LSP support are still local-only — see [Feature support over SSH](/code/ssh-feature-support/). ::: ## From prompt to production @@ -34,7 +34,7 @@ Warp’s coding agent is designed to help you generate, edit, and manage code di :::note -Warp's coding agent only works on local repositories. The agent can make changes on remote or docker repositories, but falls back to using terminal commands (i.e. `sed`, `grep` ) to make the changes. +With the [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on a remote macOS or Linux host, the coding agent applies edits using Warp's native diff tool over SSH. In sessions where the extension isn't available (Windows clients, declined installs, or Docker-backed sessions), the agent falls back to terminal commands (i.e. `sed`, `grep`) to make changes. ::: ### Examples of coding capabilities diff --git a/src/content/docs/code/ssh-feature-support.mdx b/src/content/docs/code/ssh-feature-support.mdx index 9d704d8..deccaa7 100644 --- a/src/content/docs/code/ssh-feature-support.mdx +++ b/src/content/docs/code/ssh-feature-support.mdx @@ -5,34 +5,44 @@ description: >- are limited to local sessions. --- -When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp's core terminal features — the input editor, completions, blocks, history search, and more — work the same as they do locally. However, several coding-specific features are **not yet available** in remote sessions because the Agent cannot directly access the remote filesystem. +When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp's core terminal features — the input editor, completions, blocks, history search, and more — work the same as they do locally. With Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on the remote host, additional coding features such as the file tree, native file reading, and native code diffs also work over SSH on macOS and Linux. + +This page documents which features are available based on which path you're on: + +* **SSH extension** - Installed on first connect when you choose **Install Warp's SSH extension**. Available in Preview on macOS and Linux remote hosts. +* **Tmux fallback** - Used when you choose **Continue without installing**, when the extension hasn't shipped to your build (for example, Windows clients), or when the install fails. :::note -When a native tool is unavailable, the Agent automatically falls back to terminal commands (e.g. `cat`, `sed`, `grep`) to read and edit files. You can still accomplish most coding tasks over SSH, but the experience may be less seamless than working locally. +In the tmux fallback path, the Agent automatically falls back to terminal commands (e.g. `cat`, `sed`, `grep`) when a native tool is unavailable. You can still accomplish most coding tasks, but the experience is less seamless than working locally or through the SSH extension. ::: ## Features that work over SSH -The following features are fully available in Warpified remote sessions: +The following features work in Warpified remote sessions on both paths: -* **Agent Mode conversations** — You can chat with the Agent, ask questions, and request code changes. The Agent will use terminal commands to interact with the remote filesystem. +* **Agent Mode conversations** — Chat with the Agent, ask questions, and request code changes on the remote host. * **Running shell commands** — The Agent can execute commands on the remote machine on your behalf. * **Grep and file glob** — The Agent can search for files and patterns using terminal-based grep and glob tools. * **MCP tools** — Model Context Protocol integrations remain available. * **Terminal features** — The input editor, command completions, autosuggestions, command history, blocks, and all other core terminal features work as expected. +The following features require the **SSH extension**: + +* **File tree (Project Explorer)** — The [file tree sidebar](/code/code-editor/file-tree/) reflects the remote project structure and updates as you navigate or change files. +* **Native file reading** — The Agent reads remote files through Warp's built-in file reading tool instead of shelling out to `cat`. +* **Native code diffs** — The Agent applies edits as inline [code diffs](/agent-platform/local-agents/code-diffs/) you can review and approve, instead of using `sed` or other shell commands. +* **Reliable, parallel completions** — Generators run in parallel over a single multiplexed connection, so completions stop hitting the remote host's `MaxSessions` ceiling and stop occasionally injecting errors into your blocks. + ## Features not yet available over SSH -The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions: +The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path. Each is on the SSH roadmap: -* **Codebase Context (indexing and search)** — Warp cannot index or semantically search a remote codebase. The Agent will not have access to your full project context when generating responses. Feature request: [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831) -* **Native file reading** — The Agent cannot read files through Warp's built-in file reading tool. It falls back to terminal commands like `cat` to read file contents. -* **Code diffs** — The Agent cannot apply code diffs natively. It falls back to terminal commands like `sed` to make file edits. -* **Code editor** — Warp's [native code editor](/code/code-editor/) is not yet available in remote sessions. You cannot open, view, or edit files in Warp's built-in editor over SSH. -* **File tree (Project Explorer)** — The [file tree sidebar](/code/code-editor/file-tree/) is not yet available in remote sessions. -* **Code review panel** — The [Code Review](/code/code-review/) panel for reviewing Git diffs is not yet available for remote repos. +* **Codebase Context (indexing and search)** — Warp cannot yet index or semantically search a remote codebase. The Agent does not have access to your full project context when generating responses. Tracked in [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831). +* **Code Review panel** — The [Code Review](/code/code-review/) panel for reviewing Git diffs is not yet available for remote repos. +* **Language Server Protocol (LSP)** — Warp's [LSP integration](/code/code-editor/language-server-protocol/) (hover info, go-to-definition, diagnostics, format-on-save) is local-only. +* **Code editor (file open/edit UI)** — Warp's [native code editor](/code/code-editor/) is not yet available in remote sessions. You cannot open, view, or edit remote files in Warp's built-in editor. * **Computer use** — The Agent cannot take screenshots or interact with the remote machine's desktop. :::note -WSL sessions have the same limitations as SSH. Feature request for WSL support: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744) +WSL sessions have the same limitations as SSH and are not currently covered by the SSH extension. Feature request for WSL support: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744). ::: diff --git a/src/content/docs/terminal/warpify/index.mdx b/src/content/docs/terminal/warpify/index.mdx index 946321e..bcb8863 100644 --- a/src/content/docs/terminal/warpify/index.mdx +++ b/src/content/docs/terminal/warpify/index.mdx @@ -7,7 +7,7 @@ description: >- import DemoVideo from '@components/DemoVideo.astro'; 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish. -2. [SSH](/terminal/warpify/ssh/), Warp supports a tmux powered wrapper that enables Warp features in remote (SSH) sessions. +2. [SSH](/terminal/warpify/ssh/), Warp's SSH extension brings the file tree, reliable completions, and native code diffs to remote macOS and Linux hosts, with a tmux-powered fallback for the rest. 3. [SSH Legacy](/terminal/warpify/ssh-legacy/), Warp supports a legacy wrapper that enables Warp features in remote (SSH) sessions. ## Subshells diff --git a/src/content/docs/terminal/warpify/ssh.mdx b/src/content/docs/terminal/warpify/ssh.mdx index 16316f3..abb9f12 100644 --- a/src/content/docs/terminal/warpify/ssh.mdx +++ b/src/content/docs/terminal/warpify/ssh.mdx @@ -1,61 +1,91 @@ --- title: SSH with Warp features description: >- - Warpify SSH sessions with tmux to get Blocks, completions, and the input - editor on remote machines. + Use Warp's SSH extension on remote macOS and Linux hosts to get a real file + tree, reliable completions, and native code edits over SSH. --- import VideoEmbed from '@components/VideoEmbed.astro'; +Warp's **SSH extension** brings the local Warp experience to remote macOS and Linux hosts. After you opt in on first connect, you get a real file tree backed by the remote filesystem, more reliable completions over a single multiplexed SSH connection, and a coding agent that applies edits with Warp's native diff tool instead of falling back to `sed`. + + + :::note -Some coding features — including Codebase Context, code diffs, the code editor, and the file tree — are not yet available over SSH. See [Feature support over SSH](/code/ssh-feature-support/) for the full list. +The SSH extension is rolling out to Preview on macOS and Linux. Windows remote-host support and a few coding features (Code Review, LSP, Codebase Context) are still on the roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. ::: -:::caution -This page is dedicated to the SSH features powered by `tmux`. +## What you get over SSH + +Once the SSH extension is installed on a remote host, the following features work the same way they do locally: + +* **File tree (Project Explorer)** - The left panel reflects the remote project's structure and updates as you `cd` between directories or change files. See [File Tree](/code/code-editor/file-tree/). +* **Reliable completions and autosuggestions** - Generators run in parallel over a single multiplexed connection instead of opening a new SSH session per command, so completions stop hitting the remote host's `MaxSessions` ceiling and stop occasionally injecting errors into your blocks. +* **Native file reads and code diffs** - The Agent reads files and applies edits through Warp's built-in diff tool. Code changes show up as inline diffs you can review and approve, instead of being applied via `sed` or other shell commands. See [Code diffs](/agent-platform/local-agents/code-diffs/). +* **All core terminal features** - The input editor, blocks, command history, autosuggestions, and history search behave the same as in a local session. + +Further coding improvements - including Code Review, LSP, and Codebase Context over SSH - are actively in progress and will land in subsequent Preview releases. + +![SSH](../../../../assets/terminal/warpify_ssh_prompt.png) + +## Installing the SSH extension -If you are looking to troubleshoot the legacy SSH implementation, see the [SSH (Legacy)](/terminal/warpify/ssh-legacy/). +On the first SSH connection to a host that doesn't already have the SSH extension installed, Warp shows an in-block prompt with two options: + +* **Install Warp's SSH extension** - Recommended. Warp downloads the matching `oz` binary for the remote OS and architecture, installs it under `~/.warp/remote-server` (or `~/.warp-preview/remote-server` on Preview builds), launches it, and completes the handshake. Subsequent connections to the same host skip the prompt and reuse the installed binary. +* **Continue without installing** - Falls back to the existing tmux-powered Warpification path. You still get the input editor, blocks, completions, and history, but the new file tree and native code-diff support are unavailable for this session. + +Warp never installs anything on a remote host without your explicit consent, and the install only writes under `~/.warp*/`. + +:::note +The extension binary tracks your client's release channel. Stable Warp installs `~/.warp/remote-server`, Preview installs `~/.warp-preview/remote-server`, and Dev installs `~/.warp-dev/remote-server`, so multiple channels can coexist on the same remote host. ::: - +### Managing the install prompt -Warpifying your SSH session gives you all the features of Warp while connected to a remote machine: the input editor, auto-completions, history search, and more. We achieve this by running commands like `ls` on the remote machine on your behalf. +In the Warp app, go to **Settings** > **Features** > **Warpify** to control how the prompt behaves: -**Warpifying a remote SSH Session** [**will never make lasting changes to the remote machine without your explicit consent**](/terminal/warpify/ssh/#will-warpifying-a-remote-ssh-session-make-changes-to-the-remote-machine)**.** +* **Always ask** (default) - Show the install prompt the first time you connect to each host. +* **Always install** - Skip the prompt and install the extension automatically when it's missing. +* **Never install** - Skip the prompt and always fall back to the tmux-powered path. -![SSH](../../../../assets/terminal/warpify_ssh_prompt.png) +The same setting can also be changed inline from the install prompt by selecting **Don't ask me this again** before clicking either button. The underlying TOML key is `warpify.ssh.ssh_extension_install_mode` - see [All settings reference](/terminal/settings/all-settings/#ssh) for the full list of SSH-related settings, including `ssh_hosts_denylist` for hosts you never want to engage Warpification on. + +## Fallback: tmux-powered Warpification + +If you decline the SSH extension or connect from a build that doesn't ship it (for example, Windows clients), Warp falls back to a tmux-based wrapper that still gives you Blocks, completions, the input editor, and history search. -## FAQs +### FAQs #### Will Warpifying a remote SSH session make changes to the remote machine? -Only to install [`tmux`](/terminal/warpify/ssh/#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) and only with your explicit permission. If `tmux` is not installed, Warp will offer to install it for you and will show you the list of commands that will be run. You can always decline and continue to use your ssh session without some of Warp's features (or install `tmux` yourself and re-run Warpification [via the Command Palette](/terminal/warpify/ssh/#what-if-warp-fails-to-detect-my-ssh-session)). +Only with your explicit permission. The SSH extension installs the `oz` binary under `~/.warp*/remote-server` and the tmux fallback installs [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) if it isn't already present. Both flows show you exactly what they're going to run, and you can always decline and continue using SSH without these features. #### Why do I need `tmux` on the remote machine? -`tmux` is used to asynchronously run commands on the remote machine without disrupting your interactive session. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer, which lets you run multiple sessions within one ssh connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). Warpifying a remote SSH session uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run adhoc background tasks (like those required to autocomplete a `cd` command, or populate the contents of a custom prompt). +`tmux` is only required by the fallback path. It's used to asynchronously run commands on the remote machine without disrupting your interactive session. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer that lets you run multiple sessions within one SSH connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). The fallback uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run ad-hoc background tasks like autocompleting a `cd` command or populating the contents of a custom prompt. The SSH extension supersedes this by speaking a length-delimited protocol over a single SSH connection. -#### Can I ssh to remote machines that I don't want to Warpify? +#### Can I SSH to remote machines that I don't want to Warpify? -Yes! You can always cancel Warpification and continue to use SSH, just without some of Warp's additional features. You can also explicitly add hosts to the Denylist to ensure you’re never asked to Warpify that host again. +Yes. Cancel the prompt to continue without Warp features, or add the host to the denylist (**Settings** > **Features** > **Warpify** > **SSH hosts denylist**) so you're never prompted again. -### Do I have to manually Warpify every time? +#### Do I have to manually Warpify every time? -After you successfully Warpify an SSH connection manually, we provide a brief script you can run to append a message at the end of your shell's rcfile. This allows us to know when your shell is ready to be Warpified, and be found at the bottom of your rcfile for the best results. +After you successfully Warpify an SSH connection manually, Warp provides a brief script you can run to append a marker at the end of your shell's rcfile. This lets Warp know when your remote shell is ready to be Warpified. Place the snippet at the bottom of your rcfile for the best results. ![Setting up Auto-Warpify](../../../../assets/terminal/warpify_ssh_auto_script.png) #### What shells and operating systems are supported? -At the time of writing, we support macOS and most flavors of Linux as remote hosts. Supported shells are `bash` and `zsh`. +Warp supports macOS and most flavors of Linux as remote hosts on both the SSH extension and the tmux fallback. Supported shells are `bash` and `zsh`. Windows remote hosts are not yet supported. #### What if Warp fails to detect my SSH session? -If you are ever in a remote SSH Session and would like to manually Warpify, you can do so by using the [Command Palette](/terminal/command-palette/) and searching for "Warpify SSH Session". +If you're in a remote SSH session and Warp didn't detect it, you can manually Warpify by opening the [Command Palette](/terminal/command-palette/) and searching for "Warpify SSH Session". #### What triggers SSH session detection for Warpification? -If SSH Session Detection is enabled, Warp will detect when you run an `ssh` command with arguments that suggest it's starting an interactive session. If you've aliased `ssh` or are running it as part of a script, we will not perform SSH Session Detection. +With SSH session detection enabled, Warp watches for `ssh` commands whose arguments suggest an interactive session. If you've aliased `ssh` or are running it as part of a script, Warp won't perform SSH session detection. -Once we have confidence you have successfully authenticated (by detecting `Last login:` or something resembling a basic prompt) we will prompt you to Warpify your active SSH session. +Once Warp is confident you've successfully authenticated (by detecting `Last login:` or something resembling a basic prompt), it prompts you to Warpify the active SSH session. -If SSH Session Detection does not detect your session, you can still [Warpify manually](/terminal/warpify/ssh/#what-if-warp-fails-to-detect-my-ssh-session). +If SSH session detection doesn't pick up your session, you can still [Warpify manually](#what-if-warp-fails-to-detect-my-ssh-session). From 873b655500c825e6e028b5010e0377cb8380b953 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Fri, 1 May 2026 01:23:41 +0000 Subject: [PATCH 2/6] docs: address self-review feedback on SSH PR - Fix Settings menu path: `Settings > Warpify` (not `Settings > Features > Warpify`) in three places (`terminal/warpify/ssh.mdx` lines 45 + 69 and `changelog/index.mdx`). Warpify is its own top-level Settings nav item per `app/src/settings_view/mod.rs:1210`, matching existing usage in `terminal/warpify/ssh-legacy.mdx:59` and `terminal/warpify/subshells.mdx:36`. - Replace fabricated `2026.04.29 (v0.2026.04.29.08.45)` changelog heading with a `### TBD (Preview)` placeholder + MDX comment pointing at the `update-changelog` skill so the real version stamp is added on release day instead of being merged as a guess. - Use descriptive `[SSH roadmap](...)` link text in `code/code-review.mdx` instead of `[SSH](...)`. - Lead the Codebase Context caution block with the specific feature that doesn't work ("semantic indexing and search") so the SSH-extension follow-up doesn't read as contradictory. - Lowercase `tmux` in the `**tmux fallback**` bullet of `code/ssh-feature-support.mdx` to match the rest of the docs. - Replace non-descriptive alt text (`SSH`) on the warpify prompt image with a descriptive alt text per the style guide. Co-Authored-By: Oz --- .../docs/agent-platform/capabilities/codebase-context.mdx | 4 ++-- src/content/docs/changelog/index.mdx | 8 ++++++-- src/content/docs/code/code-review.mdx | 2 +- src/content/docs/code/ssh-feature-support.mdx | 2 +- src/content/docs/terminal/warpify/ssh.mdx | 6 +++--- 5 files changed, 13 insertions(+), 9 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx index f09f98f..35613a5 100644 --- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx +++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx @@ -39,9 +39,9 @@ Code indexed with Codebase Context is never stored on our servers. Codebase Cont ::: :::caution -**Codebase Context doesn't work in SSH or WSL sessions yet.** +**Codebase Context (semantic indexing and search) is not yet available in SSH or WSL sessions.** -Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) already enables the file tree, native file reads, and native code diffs over SSH on macOS and Linux, and Codebase Context is on the SSH roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. +Other coding features over SSH on macOS and Linux — file tree, native file reads, and native code diffs — already work via Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension), and Codebase Context is on the SSH roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. Feature requests: diff --git a/src/content/docs/changelog/index.mdx b/src/content/docs/changelog/index.mdx index 9d2a190..0d0ade7 100644 --- a/src/content/docs/changelog/index.mdx +++ b/src/content/docs/changelog/index.mdx @@ -7,7 +7,11 @@ description: >- Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) -### 2026.04.29 (v0.2026.04.29.08.45) +{/* +TODO: Replace with the dated `### YYYY.MM.DD (vX.YYYY.MM.DD.HH.MM)` heading and version stamp once the Preview release ships. The `update-changelog` skill at `.warp/skills/update-changelog/` is the canonical path for filling this in from `channel-versions`. Until then, leaving the entry under a TBD heading so the build stays clean and a fabricated version can't get merged. +*/} + +### TBD (Preview) **New features** @@ -16,7 +20,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **Improvements** * \[Preview] Completions and autosuggestions over SSH are now multiplexed through the SSH extension over a single connection. This eliminates the remote host's `MaxSessions` ceiling, lets generators run in parallel, and removes the occasional errors that the previous per-command SSH session approach injected into blocks. -* Added the `warpify.ssh.ssh_extension_install_mode` setting (`always_ask`, `always_install`, `never_install`) under **Settings** > **Features** > **Warpify** to control how the SSH extension install prompt behaves. See [All settings reference](/terminal/settings/all-settings/#ssh). +* Added the `warpify.ssh.ssh_extension_install_mode` setting (`always_ask`, `always_install`, `never_install`) under **Settings** > **Warpify** to control how the SSH extension install prompt behaves. See [All settings reference](/terminal/settings/all-settings/#ssh). :::note Code Review, LSP, and Codebase Context support over SSH are still in progress and will land in subsequent Preview releases. diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx index 057eacf..f8922d7 100644 --- a/src/content/docs/code/code-review.mdx +++ b/src/content/docs/code/code-review.mdx @@ -10,7 +10,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; ## Overview :::note -The Code Review panel is currently local-only and is on the [SSH](/code/ssh-feature-support/) roadmap. +The Code Review panel is currently local-only and is on the [SSH roadmap](/code/ssh-feature-support/). ::: When you are working locally in a Git repository with uncommitted changes, the **Code Review panel** lets you inspect, edit, and manage code changes directly inside Warp. It integrates with Git and Warp's Agents, giving you the ability to: diff --git a/src/content/docs/code/ssh-feature-support.mdx b/src/content/docs/code/ssh-feature-support.mdx index deccaa7..41f7ebf 100644 --- a/src/content/docs/code/ssh-feature-support.mdx +++ b/src/content/docs/code/ssh-feature-support.mdx @@ -10,7 +10,7 @@ When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp's core terminal This page documents which features are available based on which path you're on: * **SSH extension** - Installed on first connect when you choose **Install Warp's SSH extension**. Available in Preview on macOS and Linux remote hosts. -* **Tmux fallback** - Used when you choose **Continue without installing**, when the extension hasn't shipped to your build (for example, Windows clients), or when the install fails. +* **tmux fallback** - Used when you choose **Continue without installing**, when the extension hasn't shipped to your build (for example, Windows clients), or when the install fails. :::note In the tmux fallback path, the Agent automatically falls back to terminal commands (e.g. `cat`, `sed`, `grep`) when a native tool is unavailable. You can still accomplish most coding tasks, but the experience is less seamless than working locally or through the SSH extension. diff --git a/src/content/docs/terminal/warpify/ssh.mdx b/src/content/docs/terminal/warpify/ssh.mdx index abb9f12..98eb1cd 100644 --- a/src/content/docs/terminal/warpify/ssh.mdx +++ b/src/content/docs/terminal/warpify/ssh.mdx @@ -25,7 +25,7 @@ Once the SSH extension is installed on a remote host, the following features wor Further coding improvements - including Code Review, LSP, and Codebase Context over SSH - are actively in progress and will land in subsequent Preview releases. -![SSH](../../../../assets/terminal/warpify_ssh_prompt.png) +![Warp prompting to Warpify a freshly-connected SSH session.](../../../../assets/terminal/warpify_ssh_prompt.png) ## Installing the SSH extension @@ -42,7 +42,7 @@ The extension binary tracks your client's release channel. Stable Warp installs ### Managing the install prompt -In the Warp app, go to **Settings** > **Features** > **Warpify** to control how the prompt behaves: +In the Warp app, go to **Settings** > **Warpify** to control how the prompt behaves: * **Always ask** (default) - Show the install prompt the first time you connect to each host. * **Always install** - Skip the prompt and install the extension automatically when it's missing. @@ -66,7 +66,7 @@ Only with your explicit permission. The SSH extension installs the `oz` binary u #### Can I SSH to remote machines that I don't want to Warpify? -Yes. Cancel the prompt to continue without Warp features, or add the host to the denylist (**Settings** > **Features** > **Warpify** > **SSH hosts denylist**) so you're never prompted again. +Yes. Cancel the prompt to continue without Warp features, or add the host to the denylist (**Settings** > **Warpify** > **SSH hosts denylist**) so you're never prompted again. #### Do I have to manually Warpify every time? From 54cdbab50c76b065517add02bd505e57d9c7b56d Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Fri, 1 May 2026 02:07:49 +0000 Subject: [PATCH 3/6] Remove TODO comment from changelog entry Co-Authored-By: Oz --- src/content/docs/changelog/index.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/changelog/index.mdx b/src/content/docs/changelog/index.mdx index 0d0ade7..9d62509 100644 --- a/src/content/docs/changelog/index.mdx +++ b/src/content/docs/changelog/index.mdx @@ -7,10 +7,6 @@ description: >- Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) -{/* -TODO: Replace with the dated `### YYYY.MM.DD (vX.YYYY.MM.DD.HH.MM)` heading and version stamp once the Preview release ships. The `update-changelog` skill at `.warp/skills/update-changelog/` is the canonical path for filling this in from `channel-versions`. Until then, leaving the entry under a TBD heading so the build stays clean and a fabricated version can't get merged. -*/} - ### TBD (Preview) **New features** From 0a5ea254f6b6670a1f83b00c0781e81e2318e3f9 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Fri, 1 May 2026 02:11:05 +0000 Subject: [PATCH 4/6] Remove TBD (Preview) changelog entry Co-Authored-By: Oz --- src/content/docs/changelog/index.mdx | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/content/docs/changelog/index.mdx b/src/content/docs/changelog/index.mdx index 9d62509..c49dd13 100644 --- a/src/content/docs/changelog/index.mdx +++ b/src/content/docs/changelog/index.mdx @@ -7,21 +7,6 @@ description: >- Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) -### TBD (Preview) - -**New features** - -* \[Preview] Warp's new **SSH extension** brings the local Warp experience to remote macOS and Linux hosts. On first connect, choose **Install Warp's SSH extension** to enable a real file tree backed by the remote filesystem and have the coding agent apply edits via Warp's native diff tool instead of `sed`. Choose **Continue without installing** to fall back to the existing tmux-powered Warpification path. See [SSH with Warp features](/terminal/warpify/ssh/) and [Feature support over SSH](/code/ssh-feature-support/). - -**Improvements** - -* \[Preview] Completions and autosuggestions over SSH are now multiplexed through the SSH extension over a single connection. This eliminates the remote host's `MaxSessions` ceiling, lets generators run in parallel, and removes the occasional errors that the previous per-command SSH session approach injected into blocks. -* Added the `warpify.ssh.ssh_extension_install_mode` setting (`always_ask`, `always_install`, `never_install`) under **Settings** > **Warpify** to control how the SSH extension install prompt behaves. See [All settings reference](/terminal/settings/all-settings/#ssh). - -:::note -Code Review, LSP, and Codebase Context support over SSH are still in progress and will land in subsequent Preview releases. -::: - ### 2026.04.22 (v0.2026.04.22.08.46) **New features** From a9733c5b8c2bc37fcc475a6a115b118d59e39ea0 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Fri, 1 May 2026 02:12:49 +0000 Subject: [PATCH 5/6] Remove preview/roadmap messaging from SSH docs Co-Authored-By: Oz --- src/content/docs/code/ssh-feature-support.mdx | 4 ++-- src/content/docs/terminal/warpify/ssh.mdx | 6 +----- 2 files changed, 3 insertions(+), 7 deletions(-) diff --git a/src/content/docs/code/ssh-feature-support.mdx b/src/content/docs/code/ssh-feature-support.mdx index 41f7ebf..ac49bc9 100644 --- a/src/content/docs/code/ssh-feature-support.mdx +++ b/src/content/docs/code/ssh-feature-support.mdx @@ -9,7 +9,7 @@ When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp's core terminal This page documents which features are available based on which path you're on: -* **SSH extension** - Installed on first connect when you choose **Install Warp's SSH extension**. Available in Preview on macOS and Linux remote hosts. +* **SSH extension** - Installed on first connect when you choose **Install Warp's SSH extension**. Available on macOS and Linux remote hosts. * **tmux fallback** - Used when you choose **Continue without installing**, when the extension hasn't shipped to your build (for example, Windows clients), or when the install fails. :::note @@ -35,7 +35,7 @@ The following features require the **SSH extension**: ## Features not yet available over SSH -The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path. Each is on the SSH roadmap: +The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path: * **Codebase Context (indexing and search)** — Warp cannot yet index or semantically search a remote codebase. The Agent does not have access to your full project context when generating responses. Tracked in [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831). * **Code Review panel** — The [Code Review](/code/code-review/) panel for reviewing Git diffs is not yet available for remote repos. diff --git a/src/content/docs/terminal/warpify/ssh.mdx b/src/content/docs/terminal/warpify/ssh.mdx index 98eb1cd..765c6e5 100644 --- a/src/content/docs/terminal/warpify/ssh.mdx +++ b/src/content/docs/terminal/warpify/ssh.mdx @@ -10,10 +10,6 @@ Warp's **SSH extension** brings the local Warp experience to remote macOS and Li -:::note -The SSH extension is rolling out to Preview on macOS and Linux. Windows remote-host support and a few coding features (Code Review, LSP, Codebase Context) are still on the roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. -::: - ## What you get over SSH Once the SSH extension is installed on a remote host, the following features work the same way they do locally: @@ -23,7 +19,7 @@ Once the SSH extension is installed on a remote host, the following features wor * **Native file reads and code diffs** - The Agent reads files and applies edits through Warp's built-in diff tool. Code changes show up as inline diffs you can review and approve, instead of being applied via `sed` or other shell commands. See [Code diffs](/agent-platform/local-agents/code-diffs/). * **All core terminal features** - The input editor, blocks, command history, autosuggestions, and history search behave the same as in a local session. -Further coding improvements - including Code Review, LSP, and Codebase Context over SSH - are actively in progress and will land in subsequent Preview releases. +For a full breakdown of what works over SSH and what doesn't, see [Feature support over SSH](/code/ssh-feature-support/). ![Warp prompting to Warpify a freshly-connected SSH session.](../../../../assets/terminal/warpify_ssh_prompt.png) From 3409833150425987af3c6dc3ba418d477af01a61 Mon Sep 17 00:00:00 2001 From: Oz Agent Date: Fri, 1 May 2026 18:24:54 +0000 Subject: [PATCH 6/6] docs: address PR review feedback on SSH extension docs - Use 'remote server extension' instead of 'oz binary' in ssh.mdx - Drop Dev channel mention from extension install path note - Clarify that 'Continue without installing' does not fall back to tmux - Reframe tmux-based Warpification as a legacy, deprecated alternative - Stop documenting Codebase Context, Code Review, and LSP as not yet available over SSH (these are coming very soon) Co-Authored-By: Oz --- .../capabilities/codebase-context.mdx | 2 -- .../code-editor/language-server-protocol.mdx | 2 +- src/content/docs/code/code-review.mdx | 4 ---- src/content/docs/code/overview.mdx | 4 ++-- src/content/docs/code/ssh-feature-support.mdx | 7 ++---- src/content/docs/terminal/warpify/index.mdx | 2 +- src/content/docs/terminal/warpify/ssh.mdx | 22 +++++++++++-------- 7 files changed, 19 insertions(+), 24 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx index 35613a5..56d3621 100644 --- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx +++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx @@ -41,8 +41,6 @@ Code indexed with Codebase Context is never stored on our servers. Codebase Cont :::caution **Codebase Context (semantic indexing and search) is not yet available in SSH or WSL sessions.** -Other coding features over SSH on macOS and Linux — file tree, native file reads, and native code diffs — already work via Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension), and Codebase Context is on the SSH roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. - Feature requests: * SSH: [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831) diff --git a/src/content/docs/code/code-editor/language-server-protocol.mdx b/src/content/docs/code/code-editor/language-server-protocol.mdx index 35fca7b..952f38b 100644 --- a/src/content/docs/code/code-editor/language-server-protocol.mdx +++ b/src/content/docs/code/code-editor/language-server-protocol.mdx @@ -82,7 +82,7 @@ LSP features stay in sync across [shared buffers](/code/code-editor/#shared-buff ## Limitations -* **Local sessions only** - LSP is not yet available over SSH or WSL sessions; SSH support is on the roadmap. See [Feature support over SSH](/code/ssh-feature-support/) for the current matrix. Tracked in GitHub issues [#6831](https://github.com/warpdotdev/Warp/issues/6831) (SSH) and [#6744](https://github.com/warpdotdev/Warp/issues/6744) (WSL). +* **Local sessions only** - LSP is not available over SSH or WSL sessions. These are tracked in GitHub issues [#6831](https://github.com/warpdotdev/Warp/issues/6831) (SSH) and [#6744](https://github.com/warpdotdev/Warp/issues/6744) (WSL). * **One server per language** - Each language maps to a single server (for example, Rust always uses `rust-analyzer`). Custom server configurations are not yet supported. * **Project-scoped** - Language servers operate at the Git repository root level. Files outside a repository may not receive LSP features. * **Server availability** - Some features (like formatting) depend on the specific language server's capabilities. Not all servers support all features. diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx index f8922d7..4f4a6bb 100644 --- a/src/content/docs/code/code-review.mdx +++ b/src/content/docs/code/code-review.mdx @@ -9,10 +9,6 @@ import VideoEmbed from '@components/VideoEmbed.astro'; ## Overview -:::note -The Code Review panel is currently local-only and is on the [SSH roadmap](/code/ssh-feature-support/). -::: - When you are working locally in a Git repository with uncommitted changes, the **Code Review panel** lets you inspect, edit, and manage code changes directly inside Warp. It integrates with Git and Warp's Agents, giving you the ability to: * Review diffs and attach them as context for the Agent diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx index 91cd406..04ca6ff 100644 --- a/src/content/docs/code/overview.mdx +++ b/src/content/docs/code/overview.mdx @@ -7,7 +7,7 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; :::note -On macOS and Linux SSH sessions, Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. Codebase Context, Code Review, and LSP support are still local-only — see [Feature support over SSH](/code/ssh-feature-support/). +On macOS and Linux SSH sessions, Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. See [Feature support over SSH](/code/ssh-feature-support/) for the current support matrix. ::: ## From prompt to production @@ -34,7 +34,7 @@ Warp’s coding agent is designed to help you generate, edit, and manage code di :::note -With the [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on a remote macOS or Linux host, the coding agent applies edits using Warp's native diff tool over SSH. In sessions where the extension isn't available (Windows clients, declined installs, or Docker-backed sessions), the agent falls back to terminal commands (i.e. `sed`, `grep`) to make changes. +With the [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on a remote macOS or Linux host, the coding agent applies edits using Warp's native diff tool over SSH. When the extension isn't installed, the agent falls back to terminal commands (i.e. `sed`, `grep`) to make changes. ::: ### Examples of coding capabilities diff --git a/src/content/docs/code/ssh-feature-support.mdx b/src/content/docs/code/ssh-feature-support.mdx index ac49bc9..5e7a75f 100644 --- a/src/content/docs/code/ssh-feature-support.mdx +++ b/src/content/docs/code/ssh-feature-support.mdx @@ -10,10 +10,10 @@ When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp's core terminal This page documents which features are available based on which path you're on: * **SSH extension** - Installed on first connect when you choose **Install Warp's SSH extension**. Available on macOS and Linux remote hosts. -* **tmux fallback** - Used when you choose **Continue without installing**, when the extension hasn't shipped to your build (for example, Windows clients), or when the install fails. +* **Legacy tmux-based Warpification** - An older alternative that's being deprecated. It remains available today for clients that don't yet ship the SSH extension (for example, Windows clients). See [Legacy: tmux-based Warpification](/terminal/warpify/ssh/#legacy-tmux-based-warpification). :::note -In the tmux fallback path, the Agent automatically falls back to terminal commands (e.g. `cat`, `sed`, `grep`) when a native tool is unavailable. You can still accomplish most coding tasks, but the experience is less seamless than working locally or through the SSH extension. +When a native tool isn't available on the current path, the Agent falls back to terminal commands (e.g. `cat`, `sed`, `grep`). You can still accomplish most coding tasks, but the experience is less seamless than working locally or through the SSH extension. ::: ## Features that work over SSH @@ -37,9 +37,6 @@ The following features require the **SSH extension**: The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path: -* **Codebase Context (indexing and search)** — Warp cannot yet index or semantically search a remote codebase. The Agent does not have access to your full project context when generating responses. Tracked in [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831). -* **Code Review panel** — The [Code Review](/code/code-review/) panel for reviewing Git diffs is not yet available for remote repos. -* **Language Server Protocol (LSP)** — Warp's [LSP integration](/code/code-editor/language-server-protocol/) (hover info, go-to-definition, diagnostics, format-on-save) is local-only. * **Code editor (file open/edit UI)** — Warp's [native code editor](/code/code-editor/) is not yet available in remote sessions. You cannot open, view, or edit remote files in Warp's built-in editor. * **Computer use** — The Agent cannot take screenshots or interact with the remote machine's desktop. diff --git a/src/content/docs/terminal/warpify/index.mdx b/src/content/docs/terminal/warpify/index.mdx index bcb8863..5c5e50d 100644 --- a/src/content/docs/terminal/warpify/index.mdx +++ b/src/content/docs/terminal/warpify/index.mdx @@ -7,7 +7,7 @@ description: >- import DemoVideo from '@components/DemoVideo.astro'; 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish. -2. [SSH](/terminal/warpify/ssh/), Warp's SSH extension brings the file tree, reliable completions, and native code diffs to remote macOS and Linux hosts, with a tmux-powered fallback for the rest. +2. [SSH](/terminal/warpify/ssh/), Warp's SSH extension brings the file tree, reliable completions, and native code diffs to remote macOS and Linux hosts. Legacy tmux-based Warpification is still available for clients that don't yet ship the extension. 3. [SSH Legacy](/terminal/warpify/ssh-legacy/), Warp supports a legacy wrapper that enables Warp features in remote (SSH) sessions. ## Subshells diff --git a/src/content/docs/terminal/warpify/ssh.mdx b/src/content/docs/terminal/warpify/ssh.mdx index 765c6e5..576f841 100644 --- a/src/content/docs/terminal/warpify/ssh.mdx +++ b/src/content/docs/terminal/warpify/ssh.mdx @@ -27,13 +27,13 @@ For a full breakdown of what works over SSH and what doesn't, see [Feature suppo On the first SSH connection to a host that doesn't already have the SSH extension installed, Warp shows an in-block prompt with two options: -* **Install Warp's SSH extension** - Recommended. Warp downloads the matching `oz` binary for the remote OS and architecture, installs it under `~/.warp/remote-server` (or `~/.warp-preview/remote-server` on Preview builds), launches it, and completes the handshake. Subsequent connections to the same host skip the prompt and reuse the installed binary. -* **Continue without installing** - Falls back to the existing tmux-powered Warpification path. You still get the input editor, blocks, completions, and history, but the new file tree and native code-diff support are unavailable for this session. +* **Install Warp's SSH extension** - Recommended. Warp downloads the matching remote server extension for the remote OS and architecture, installs it under `~/.warp/remote-server` (or `~/.warp-preview/remote-server` on Preview builds), launches it, and completes the handshake. Subsequent connections to the same host skip the prompt and reuse the installed binary. +* **Continue without installing** - Skip installing the extension for this connection. The session continues without the SSH extension, so file tree, native file reads, and native code diffs are unavailable until you install. You can reconnect and install at any time. Warp never installs anything on a remote host without your explicit consent, and the install only writes under `~/.warp*/`. :::note -The extension binary tracks your client's release channel. Stable Warp installs `~/.warp/remote-server`, Preview installs `~/.warp-preview/remote-server`, and Dev installs `~/.warp-dev/remote-server`, so multiple channels can coexist on the same remote host. +The extension binary tracks your client's release channel. Stable Warp installs the extension under `~/.warp/remote-server`, and Preview installs it under `~/.warp-preview/remote-server`, so both channels can coexist on the same remote host. ::: ### Managing the install prompt @@ -42,23 +42,27 @@ In the Warp app, go to **Settings** > **Warpify** to control how the prompt beha * **Always ask** (default) - Show the install prompt the first time you connect to each host. * **Always install** - Skip the prompt and install the extension automatically when it's missing. -* **Never install** - Skip the prompt and always fall back to the tmux-powered path. +* **Never install** - Skip the prompt and connect to the host without installing the SSH extension. The same setting can also be changed inline from the install prompt by selecting **Don't ask me this again** before clicking either button. The underlying TOML key is `warpify.ssh.ssh_extension_install_mode` - see [All settings reference](/terminal/settings/all-settings/#ssh) for the full list of SSH-related settings, including `ssh_hosts_denylist` for hosts you never want to engage Warpification on. -## Fallback: tmux-powered Warpification +## Legacy: tmux-based Warpification -If you decline the SSH extension or connect from a build that doesn't ship it (for example, Windows clients), Warp falls back to a tmux-based wrapper that still gives you Blocks, completions, the input editor, and history search. +:::caution +Tmux-based Warpification is a legacy alternative to the SSH extension and is being deprecated. Use the SSH extension above whenever possible. Tmux-based Warpification remains available today for clients that don't yet ship the SSH extension (for example, Windows clients). +::: + +Tmux-based Warpification is an older approach to enabling Warp features in SSH sessions. It uses [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) to multiplex commands over your SSH connection and provides Blocks, completions, the input editor, and history search. ### FAQs #### Will Warpifying a remote SSH session make changes to the remote machine? -Only with your explicit permission. The SSH extension installs the `oz` binary under `~/.warp*/remote-server` and the tmux fallback installs [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) if it isn't already present. Both flows show you exactly what they're going to run, and you can always decline and continue using SSH without these features. +Only with your explicit permission. The SSH extension installs the remote server extension under `~/.warp*/remote-server`. Legacy tmux-based Warpification installs [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) if it isn't already present. Both flows show you exactly what they're going to run, and you can always decline and continue using SSH without these features. #### Why do I need `tmux` on the remote machine? -`tmux` is only required by the fallback path. It's used to asynchronously run commands on the remote machine without disrupting your interactive session. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer that lets you run multiple sessions within one SSH connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). The fallback uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run ad-hoc background tasks like autocompleting a `cd` command or populating the contents of a custom prompt. The SSH extension supersedes this by speaking a length-delimited protocol over a single SSH connection. +`tmux` is only required by the legacy tmux-based Warpification path; the SSH extension does not need it. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer that lets you run multiple sessions within one SSH connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). The legacy path uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run ad-hoc background tasks like autocompleting a `cd` command or populating the contents of a custom prompt. The SSH extension supersedes this by speaking a length-delimited protocol over a single SSH connection. #### Can I SSH to remote machines that I don't want to Warpify? @@ -72,7 +76,7 @@ After you successfully Warpify an SSH connection manually, Warp provides a brief #### What shells and operating systems are supported? -Warp supports macOS and most flavors of Linux as remote hosts on both the SSH extension and the tmux fallback. Supported shells are `bash` and `zsh`. Windows remote hosts are not yet supported. +Warp supports macOS and most flavors of Linux as remote hosts on both the SSH extension and legacy tmux-based Warpification. Supported shells are `bash` and `zsh`. Windows remote hosts are not yet supported. #### What if Warp fails to detect my SSH session?