Skip to main content
Warp extends its terminal features to remote SSH sessions through a mechanism called warpify. When you SSH into a remote machine, Warp can optionally install a small server-side component that bridges the remote shell back to Warp’s local UI, giving you blocks, completions, and AI tools even on a server where Warp is not installed. On Windows, Warp also integrates with WSL (Windows Subsystem for Linux) to let you run Linux distros as first-class Warp sessions.

​
How warpify works

When Warp detects that you have started an interactive SSH session, it offers to warpify the connection. Warpification installs a remote component on the server (the SSH extension binary) and sets up a communication channel between the local Warp process and the remote shell. Once connected, the remote session behaves like a local Warp session: commands create blocks, completions work, and the AI agent can read terminal output.
1

Start an SSH connection

Run a standard SSH command in your Warp terminal:
ssh user@example.com
Warp’s shell detection layer (ssh_detection.rs) recognizes the interactive SSH pattern and evaluates whether to offer warpification.
2

Accept the warpify prompt

If warpification is enabled and the host is not on your denylist, Warp displays a SshWarpifyBlock prompt in the terminal. Click Warpify session (or press Enter) to begin. Press Ctrl+C or Cancel to proceed without warpification.
3

Install the SSH extension

If the remote host does not already have the Warp SSH extension installed, Warp will prompt you to install it. The install behavior is controlled by warpify.ssh.ssh_extension_install_mode:
ModeBehavior
always_ask (default)Prompt before installing
always_installInstall automatically without prompting
never_installSkip installation; fall back to legacy warpification
4

Use Warp features remotely

Once the extension is running, the remote session becomes a fully featured Warp session. Commands create blocks, the block toolbar is available, and completions draw from the remote shell’s environment.
The warpify.ssh.enable_ssh_warpification setting controls whether Warp ever offers to warpify SSH sessions. Set it to false to disable the prompt entirely:
[warpify.ssh]
enable_ssh_warpification = false

​
SSH tmux wrapper

As an alternative to the SSH extension, Warp provides an SSH tmux wrapper that uses tmux on the remote machine to preserve the session structure. This mode is enabled by setting warpify.ssh.use_ssh_tmux_wrapper = true and requires the SSHTmuxWrapper feature flag. When the tmux wrapper is active:
  • Warp wraps the SSH session inside a tmux server on the remote machine.
  • If tmux is not installed, Warp offers to install it automatically (via the SshInstallTmuxBlockEvent::InstallTmuxAndWarpify flow).
  • The tmux session persists even if your local connection drops, so you can reconnect and resume where you left off.
[warpify.ssh]
use_ssh_tmux_wrapper = true
The tmux wrapper is currently supported on macOS and Linux hosts (not Windows remote targets). See the tmux installation docs for more detail on why tmux is required.

​
Configuring SSH hosts and subshells

​
Denylist hosts

If you have SSH hosts where you never want Warp to offer warpification — for example, production jump hosts or hosts where you lack install permissions — add them to the host denylist. The list accepts regex patterns: 
[warpify.ssh]
ssh_hosts_denylist = ["prod-.*\\.example\\.com", "jump-host"]

​
Denylist and allowlist subshell commands

Warpify also applies to subshell commands — commands that open an interactive sub-process that behaves like a shell (for example, bash, poetry shell, pipenv shell). You can control which commands trigger the warpification prompt: 
[warpify.subshells]
# Patterns added here trigger the warpification prompt
added_subshell_commands = ["my-custom-shell"]

# Patterns added here suppress the prompt even for known-compatible subshells
subshell_commands_denylist = ["poetry shell"]
Warp recognizes several subshells automatically, including bash, zsh, fish, poetry shell, and pipenv shell.

​
Drag and drop over SSH

When the SshDragAndDrop feature is enabled, you can drag files from your local machine directly into a Warp SSH session. Warp transfers the file to the remote host and inserts the remote path into the command input, just as it would for a local drag-and-drop operation.

​
WSL on Windows

On Windows, Warp integrates with Windows Subsystem for Linux (WSL) to surface installed Linux distributions as selectable shell sessions. Warp reads the WSL registry key (Software\Microsoft\Windows\CurrentVersion\Lxss) to enumerate available distributions, marks the default distribution, and filters out tool-managed entries like Docker Desktop and Rancher Desktop. To open a WSL session, click the shell picker in the Warp tab bar and select the distribution you want (for example, Ubuntu or Ubuntu-18.04). Warp launches a Warp-native session inside that distribution, giving you blocks and completions in the Linux environment.
If WSL is not installed or not enabled on your Windows machine, Warp logs a warning and the WSL distributions simply do not appear in the shell picker. There is no error shown to the user.
Warp also recognizes wsl and wsl.exe commands typed in a PowerShell or CMD session and can offer to warpify them as subshell sessions, subject to the subshell denylist rules.

​
Shared sessions

Beyond single-user SSH, Warp supports shared sessions — live terminal sessions that multiple users can view simultaneously. The sharer’s terminal size is broadcast to viewers, and the session content is synchronized in real time. Shared sessions use a separate shared_session module distinct from the SSH layer, but they pair naturally with remote development workflows.

​
Troubleshooting SSH connections

Check that warpify.ssh.enable_ssh_warpification is true and that the SSH host is not in your ssh_hosts_denylist. Also confirm that the SSHTmuxWrapper feature flag is enabled if you are using the tmux wrapper path.
Warp waits up to 8 seconds for the warpification handshake to complete (SSH_WARPIFY_TIMEOUT_DURATION). If the remote machine is slow or the network is high-latency, the prompt may time out. Try again or set ssh_extension_install_mode = "never_install" to fall back to legacy mode.
When using the tmux wrapper, Warp detects that tmux is missing and displays an install prompt. You can choose a package-manager install (for example, apt-get install tmux) or provide a custom install script.
Ensure WSL is enabled (wsl --install in PowerShell as Administrator) and that at least one distribution is installed. Docker Desktop and Rancher Desktop WSL instances are intentionally excluded from the picker.

Build docs developers (and LLMs) love

Get started for freeTalk to us