Skip to content

SSH

wezterm uses an embedded ssh library to provide an integrated SSH client. The client can be used to make ad-hoc SSH connections to remote hosts by invoking the client like this:

$ wezterm ssh wez@my.server

(checkout wezterm ssh -h for more options).

When invoked in this way, wezterm may prompt you for SSH authentication and once a connection is established, open a new terminal window with your requested command, or your shell if you didn't specify one.

Creating new tabs or panes will each create a new channel in your existing session so you won't need to re-authenticate for additional tabs that you create.

SSH sessions created in this way are non-persistent and all associated tabs will die if your network connection is interrupted.

Take a look at the multiplexing section for an alternative configuration that connects to a remote wezterm instance and preserves your tabs.

The ssh_backend configuration can be used to specify which ssh library is used.

Since: Version 20210404-112810-b63a949d

The functionality described in this section requires version 20210404-112810-b63a949d of wezterm, or a more recent version.

wezterm is now able to parse ~/.ssh/config and /etc/ssh/ssh_config and respects the following options:

  • IdentityAgent
  • IdentityFile
  • Hostname
  • User
  • Port
  • ProxyCommand
  • Host (including wildcard matching)
  • UserKnownHostsFile
  • IdentitiesOnly
  • BindAddress

All other options are parsed but have no effect. Notably, neither Match or Include will do anything.

Since: Version 20210502-154244-3f7122cb:

The functionality described in this section requires version 20210502-154244-3f7122cb: of wezterm, or a more recent version.

Match is now recognized but currently supports only single-phase (final, canonical are not supported) configuration parsing for Host and LocalUser. Exec based matches are recognized but not supported.

Since: Version 20210814-124438-54e29167:

The functionality described in this section requires version 20210814-124438-54e29167: of wezterm, or a more recent version.

Include is now supported.

Since: Nightly Builds Only

The functionality described in this section requires a nightly build of wezterm. You can obtain a nightly build by following the instructions from the Download section.

ProxyUseFDpass is now supported. (But not on Microsoft Windows).

CLI Overrides

wezterm ssh CLI allows overriding config settings via the command line. This example shows how to specify the private key to use when connecting to some-host:

wezterm ssh -oIdentityFile=/secret/id_ed25519 some-host