> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# SSH and remote development in Warp

> Connect to remote servers over SSH and bring Warp's blocks, completions, and AI to your remote session via warpify, with optional tmux and WSL support.

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.

<Steps>
  <Step title="Start an SSH connection">
    Run a standard SSH command in your Warp terminal:

    ```bash theme={null}
    ssh user@example.com
    ```

    Warp's shell detection layer (`ssh_detection.rs`) recognizes the interactive SSH pattern and evaluates whether to offer warpification.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`:

    | Mode                   | Behavior                                             |
    | ---------------------- | ---------------------------------------------------- |
    | `always_ask` (default) | Prompt before installing                             |
    | `always_install`       | Install automatically without prompting              |
    | `never_install`        | Skip installation; fall back to legacy warpification |
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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:

  ```toml theme={null}
  [warpify.ssh]
  enable_ssh_warpification = false
  ```
</Note>

## 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.

```toml theme={null}
[warpify.ssh]
use_ssh_tmux_wrapper = true
```

<Tip>
  The tmux wrapper is currently supported on macOS and Linux hosts (not Windows remote targets). See the [tmux installation docs](https://docs.warp.dev/terminal/warpify/ssh#why-do-i-need-tmux-on-the-remote-machine) for more detail on why tmux is required.
</Tip>

## 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:

```toml theme={null}
[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:

```toml theme={null}
[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.

<Note>
  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.
</Note>

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

<AccordionGroup>
  <Accordion title="The warpify prompt does not appear">
    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.
  </Accordion>

  <Accordion title="Extension installation times out">
    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.
  </Accordion>

  <Accordion title="tmux is not found on the remote machine">
    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.
  </Accordion>

  <Accordion title="WSL distributions are not listed on Windows">
    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.
  </Accordion>
</AccordionGroup>