Skip to main content
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 OptionSupported
Host✓
Hostname✓
User✓
Port✓
IdentityFile✓
IdentityAgent✓
IdentitiesOnly✓
ProxyCommand✓
ProxyUseFDpass✓ (not on Windows)
UserKnownHostsFile✓
BindAddress✓
ServerAliveInterval✓ (libssh backend)
Include✓
MatchPartial (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

FeatureLibsshSsh2
ServerAliveInterval✓✗
ProxyUseFDpass✓✗
StabilityHighHigh
PerformanceGoodGood

​
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 "[email protected]"

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

# 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

FeatureWezTerm SSHOpenSSHPuTTY
Config file support✓✓Partial
Tab multiplexing✓✗✗
Native GUI✓✗✓
Session persistence✓ (with domains)✗✗
Cross-platform✓✓Windows only
Key agent support✓✓✓

Build docs developers (and LLMs) love

Get started for freeTalk to us