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

# SSH Client

> Built-in SSH client with multiplexing, config file support, and integrated terminal sessions

WezTerm includes an embedded SSH client library that provides an integrated SSH experience with native terminal multiplexing support. You can connect to remote hosts without installing a separate SSH client, and new tabs automatically reuse existing connections.

## Basic SSH Usage

Connect to a remote host directly from the command line:

```bash Connect to Remote Host theme={null}
wezterm ssh user@hostname

# With custom port
wezterm ssh user@hostname:2222

# View all options
wezterm ssh -h
```

## How It Works

When you connect via `wezterm ssh`:

1. WezTerm establishes an SSH connection to the remote host
2. A new terminal window opens with your session
3. New tabs/panes created from this window reuse the same SSH connection
4. No re-authentication required for additional tabs

<Note>
  SSH sessions created with `wezterm ssh` are non-persistent. If your network connection is interrupted, all associated tabs will close. For persistent sessions, see the multiplexing domains section below.
</Note>

## SSH Config File Support

WezTerm reads and respects your SSH configuration from:

* `~/.ssh/config`
* `/etc/ssh/ssh_config`

### Supported Options

| SSH Config Option     |             Supported             |
| --------------------- | :-------------------------------: |
| `Host`                |                 ✓                 |
| `Hostname`            |                 ✓                 |
| `User`                |                 ✓                 |
| `Port`                |                 ✓                 |
| `IdentityFile`        |                 ✓                 |
| `IdentityAgent`       |                 ✓                 |
| `IdentitiesOnly`      |                 ✓                 |
| `ProxyCommand`        |                 ✓                 |
| `ProxyUseFDpass`      |         ✓ (not on Windows)        |
| `UserKnownHostsFile`  |                 ✓                 |
| `BindAddress`         |                 ✓                 |
| `ServerAliveInterval` |         ✓ (libssh backend)        |
| `Include`             |                 ✓                 |
| `Match`               | Partial (Host and LocalUser only) |

### Example SSH Config

```ssh ~/.ssh/config theme={null}
Host myserver
    Hostname 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60

Host *.example.com
    User deploy
    IdentityFile ~/.ssh/deploy_key
    ProxyCommand ssh bastion -W %h:%p
```

Connect using the alias:

```bash Use Config Alias theme={null}
wezterm ssh myserver
```

## Command-Line Overrides

Override SSH config settings from the command line:

```bash CLI Overrides theme={null}
# Override identity file
wezterm ssh -oIdentityFile=/secret/id_ed25519 myserver

# Multiple overrides
wezterm ssh -oPort=2222 -oUser=admin some-host

# Override any config option
wezterm ssh -oServerAliveInterval=30 myserver
```

## SSH Backends

WezTerm supports multiple SSH backend implementations:

```lua Configure SSH Backend theme={null}
local wezterm = require 'wezterm'
local config = {}

-- Use libssh (default)
config.ssh_backend = 'Libssh'

-- Or use the SSH2 backend
-- config.ssh_backend = 'Ssh2'

return config
```

### Backend Comparison

| Feature             | Libssh | Ssh2 |
| ------------------- | :----: | :--: |
| ServerAliveInterval |    ✓   |   ✗  |
| ProxyUseFDpass      |    ✓   |   ✗  |
| Stability           |  High  | High |
| Performance         |  Good  | Good |

## Multiplexing Domains

For persistent SSH sessions that survive network interruptions, configure SSH multiplexing domains. This requires WezTerm to be installed on both local and remote hosts.

### Configuring SSH Domains

```lua SSH Domain Configuration theme={null}
local wezterm = require 'wezterm'
local config = {}

config.ssh_domains = {
  {
    -- Domain identifier
    name = 'production',
    -- Remote address
    remote_address = '192.168.1.1',
    -- Remote username
    username = 'deploy',
  },
  {
    name = 'staging',
    remote_address = 'staging.example.com',
    username = 'admin',
    -- Specify port if non-standard
    remote_wezterm_path = '/usr/local/bin/wezterm',
  },
}

return config
```

### Connecting to SSH Domains

```bash Connect to Multiplexing Domain theme={null}
wezterm connect production
```

This:

1. Establishes SSH connection to the remote host
2. Starts or connects to the WezTerm multiplexer daemon on the remote
3. Attaches tabs through a Unix domain socket over SSH
4. Persists sessions even if network connection drops

### Auto-Generated Domains

SSH domains are automatically created from your `~/.ssh/config`:

* **Plain SSH**: Prefix `SSH:` (e.g., `SSH:myserver`)
* **Multiplexing**: Prefix `SSHMUX:` (e.g., `SSHMUX:myserver`)

```bash Auto-Generated Domains theme={null}
# Regular SSH connection
wezterm connect SSH:myserver

# Multiplexing SSH connection
wezterm connect SSHMUX:myserver

# Or spawn in existing GUI
wezterm cli spawn --domain-name SSHMUX:myserver
```

## Authentication

### SSH Key Authentication

Recommended for security and convenience:

```bash Generate SSH Key theme={null}
# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -C "your_email@example.com"

# Or RSA key (4096 bits minimum)
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Copy public key to remote host
ssh-copy-id user@hostname
```

### SSH Agent

WezTerm respects `IdentityAgent` configuration:

```ssh SSH Agent Config theme={null}
Host *
    IdentityAgent ~/.ssh/agent.sock
```

## Advanced Configuration

### Jump Hosts / Bastion

```ssh Bastion Configuration theme={null}
Host bastion
    Hostname bastion.example.com
    User jumper
    IdentityFile ~/.ssh/bastion_key

Host internal-*
    ProxyCommand ssh bastion -W %h:%p
    User admin
```

### Connection Keepalive

```ssh Keep Connection Alive theme={null}
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3
```

<Note>
  `ServerAliveInterval` is supported by the `libssh` backend. `ServerAliveCountMax` is not currently supported.
</Note>

### Multiple Identity Files

```ssh Multiple Keys theme={null}
Host github.com
    IdentityFile ~/.ssh/github_personal
    IdentityFile ~/.ssh/github_work
    IdentitiesOnly yes
```

## Troubleshooting

### Connection Timeout

```lua Increase Timeout theme={null}
config.ssh_domains = {
  {
    name = 'slow-server',
    remote_address = 'slow.example.com',
    username = 'user',
    timeout = 120, -- seconds
  },
}
```

### Authentication Failures

<Steps>
  <Step title="Check SSH key permissions">
    Ensure private keys have correct permissions: `chmod 600 ~/.ssh/id_ed25519`
  </Step>

  <Step title="Verify SSH agent">
    Check if agent is running: `ssh-add -l`
  </Step>

  <Step title="Test connection">
    Try standard SSH client first: `ssh -v user@hostname`
  </Step>

  <Step title="Check known_hosts">
    Remove old host keys if host was reinstalled: `ssh-keygen -R hostname`
  </Step>
</Steps>

### Remote WezTerm Not Found

For SSH multiplexing domains, specify the remote WezTerm path:

```lua Remote WezTerm Path theme={null}
config.ssh_domains = {
  {
    name = 'remote',
    remote_address = 'host.example.com',
    username = 'user',
    remote_wezterm_path = '/opt/wezterm/bin/wezterm',
  },
}
```

## Use Cases

### Development Workflow

```bash Dev Server Connection theme={null}
# Connect to development server
wezterm ssh dev-server

# Tab 1: Run application
npm start

# Tab 2: Watch logs (new tab reuses connection)
tail -f app.log

# Tab 3: Run tests
npm test
```

### System Administration

```bash Multi-Host Management theme={null}
# Connect to multiple servers
wezterm ssh prod-web-01
wezterm ssh prod-web-02  
wezterm ssh prod-db-01

# Or use multiplexing domains for persistence
wezterm connect SSHMUX:prod-web-01
```

### Remote Development

```bash Remote Coding theme={null}
# Connect with multiplexing for persistence
wezterm connect SSHMUX:dev-server

# Session persists through network changes
# Reconnect to same session after disconnect
wezterm connect SSHMUX:dev-server
```

## Comparison to Other SSH Clients

| Feature             |    WezTerm SSH   | OpenSSH |     PuTTY    |
| ------------------- | :--------------: | :-----: | :----------: |
| Config file support |         ✓        |    ✓    |    Partial   |
| Tab multiplexing    |         ✓        |    ✗    |       ✗      |
| Native GUI          |         ✓        |    ✗    |       ✓      |
| Session persistence | ✓ (with domains) |    ✗    |       ✗      |
| Cross-platform      |         ✓        |    ✓    | Windows only |
| Key agent support   |         ✓        |    ✓    |       ✓      |