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:

Connect to Remote Host

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

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.

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/config

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:

Use Config Alias

wezterm ssh myserver

Command-Line Overrides

Override SSH config settings from the command line:

CLI Overrides

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

Configure SSH Backend

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

SSH Domain Configuration

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

Connect to Multiplexing Domain

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)

Auto-Generated Domains

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

Generate SSH Key

# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -C "[e-mail]"

# Or RSA key (4096 bits minimum)
ssh-keygen -t rsa -b 4096 -C "[e-mail]"

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

SSH Agent

WezTerm respects IdentityAgent configuration:

SSH Agent Config

Host *
    IdentityAgent ~/.ssh/agent.sock

Advanced Configuration

Jump Hosts / Bastion

Bastion Configuration

Host bastion
    Hostname bastion.example.com
    User jumper
    IdentityFile ~/.ssh/bastion_key

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

Connection Keepalive

Keep Connection Alive

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

ServerAliveInterval is supported by the libssh backend. ServerAliveCountMax is not currently supported.

Multiple Identity Files

Multiple Keys

Host github.com
    IdentityFile ~/.ssh/github_personal
    IdentityFile ~/.ssh/github_work
    IdentitiesOnly yes

Troubleshooting

Connection Timeout

Increase Timeout

config.ssh_domains = {
  {
    name = 'slow-server',
    remote_address = 'slow.example.com',
    username = 'user',
    timeout = 120, -- seconds
  },
}

Authentication Failures

1. Check SSH key permissions

   Ensure private keys have correct permissions: chmod 600 ~/.ssh/id_ed25519

2. Verify SSH agent

   Check if agent is running: ssh-add -l

3. Test connection

   Try standard SSH client first: ssh -v user@hostname

4. Check known_hosts

   Remove old host keys if host was reinstalled: ssh-keygen -R hostname

Remote WezTerm Not Found

For SSH multiplexing domains, specify the remote WezTerm path:

Remote WezTerm Path

config.ssh_domains = {
  {
    name = 'remote',
    remote_address = 'host.example.com',
    username = 'user',
    remote_wezterm_path = '/opt/wezterm/bin/wezterm',
  },
}

Use Cases

Development Workflow

Dev Server Connection

# 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

Multi-Host Management

# 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

Remote Coding

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