Skip to main content
The ssh command establishes an SSH connection to a remote system using WezTerm’s built-in SSH client.

​
Synopsis

wezterm ssh [OPTIONS] <USER_AT_HOST_AND_PORT> [PROG]...

​
Description

Establishes an SSH session to a remote system. WezTerm includes a built-in SSH client that can parse SSH configuration files and provides a native terminal experience with full feature support.

​
Arguments

​
USER_AT_HOST_AND_PORT
string
required
Specifies the remote system using the form: [username@]host[:port]
  • If username@ is omitted, your local $USER is used
  • If :port is omitted, the standard SSH port (22) is used
Examples:
wezterm ssh user@example.com
wezterm ssh example.com:2222
wezterm ssh user@example.com:2222
wezterm ssh example.com
​
PROG
string[]
Instead of executing your shell, run PROG on the remote system.Example:
wezterm ssh user@host -- bash -l
This will spawn bash as if it were a login shell on the remote system.

​
Options

​
-o, --ssh-option
name=value
Override specific SSH configuration options. Can be specified multiple times.WezTerm’s SSH client can parse some (but not all!) options from your ~/.ssh/config and /etc/ssh/ssh_config files. This command line switch allows you to override or otherwise specify ssh_config style options.Example:
wezterm ssh -oIdentityFile=/secret/id_ed25519 some-host
wezterm ssh -oPort=2222 -oUser=admin example.com
​
-v
flag
Enable verbose SSH protocol tracing.The trace information is printed to the stderr stream of the process. Useful for debugging connection issues.
​
--class
string
Override the default windowing system class. The default is org.wezfurlong.wezterm.
  • Under X11 and Windows: changes the window class
  • Under Wayland: changes the app_id
This changes the class for all windows spawned by this instance of wezterm, including error, update and ssh authentication dialogs.
​
--position
string
Override the position for the initial window launched by this process.Format options:
  • --position 10,20 - set x=10, y=20 in screen coordinates
  • --position screen:10,20 - set x=10, y=20 in screen coordinates
  • --position main:10,20 - set x=10, y=20 relative to the main monitor
  • --position active:10,20 - set x=10, y=20 relative to the active monitor
  • --position HDMI-1:10,20 - set x=10, y=20 relative to the monitor named HDMI-1

​
Examples

​
Basic SSH connection

wezterm ssh user@example.com

​
Connect to non-standard port

wezterm ssh user@example.com:2222

​
Use specific identity file

wezterm ssh -oIdentityFile=~/.ssh/id_custom user@example.com

​
Multiple SSH options

wezterm ssh -oPort=2222 -oUser=admin -oIdentityFile=/path/to/key example.com

​
Enable verbose debugging

wezterm ssh -v user@example.com

​
Run a specific command

wezterm ssh user@example.com -- htop

​
Open at specific window position

wezterm ssh --position main:0,0 user@example.com

​
SSH Configuration

WezTerm respects your SSH configuration files:
  • ~/.ssh/config
  • /etc/ssh/ssh_config
You can define host aliases and settings in these files, and WezTerm will use them: 
Host myserver
    HostName example.com
    User myuser
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
Then simply: 
wezterm ssh myserver

​
Features

  • Built-in SSH client (no external SSH binary required)
  • Supports SSH agent forwarding
  • Respects SSH config files
  • Full terminal feature support (colors, mouse, clipboard, etc.)
  • Integrated with WezTerm’s multiplexer capabilities