wezterm/docs/multiplexing.markdown

title
Multiplexing

Notice: multiplexing is still a young feature and is evolving rapidly. Your feedback is welcomed!

Multiplexing

The out-of-the-box experience with wezterm allows you to multiplex local tabs and windows which will persist until they are closed. With a little extra configuration you can enable local terminal multiplexing with features similar to those in tmux or screen.

Multiplexing in wezterm is based around the concept of multiplexing domains; a domain is a distinct set of windows and tabs. When wezterm starts up it creates a default local domain to manage the windows and tabs in the UI, but it can also be configured to start or connect to any number of additional domains.

Once connected to a domain, wezterm can attach its windows and tabs to the local native UI, providing a more natural experience for interacting with the mouse, clipboard and scrollback features of the terminal.

Key bindings allow you to spawn new tabs in the default local domain, the domain of the current tab, or a specific numbered domain.

SSH Domains

wezterm also supports regular ad-hoc ssh connections. This section of the docs refers to running a wezterm daemon on the remote end of a multiplexing session that uses ssh as a channel

A connection to a remote wezterm multiplexer made via an ssh connection is referred to as an SSH domain. A compatible version of wezterm must be installed on the remote system in order to use SSH domains. SSH domains are supported on all systems via libssh2.

To configure an SSH domain, place something like the following in your wezterm.toml file:

[[ssh_domains]]
# This name identifies the domain
name = "my.server"
# The address to connect to
remote_address = "192.168.1.1"
# The username to use on the remote host
username = "wez"

To connect to the system, run:

$ wezterm connect my.server

This will launch an SSH session that connects to the specified address and may pop up authentication dialogs (using SSH keys for auth is strongly recommended!). Once connected, it will attempt to spawn the wezterm multiplexer daemon on the remote host and connect to it via a unix domain socket using a similar mechanism to that described in the Unix Domains section below.

Unix Domains

A connection to a multiplexer made via a unix socket is referred to as a unix domain. Unix domains are supported on all systems, even Windows and are a way to connect the native win32 GUI into the Windows Subsystem for Linux (WSL).

The bare minimum configuration to enable a unix domain is this, which will spawn a server if needed and then connect the gui to it automatically when wezterm is launched:

[[unix_domains]]
name = "unix"
connect_automatically = true

If you prefer to connect manually, omit the connect_automatically setting (or set it to false) and then run:

$ wezterm connect unix

The possible configuration values are:

[[unix_domains]]
name = "unix"
# If true, connect to this unix domain when `wezterm` is started
connect_automatically = true

# The path to the socket.  If unspecified, a resonable default
# value will be computed.
# socket_path = "/some/path"

# If true, do not attempt to start this server if we try and fail to
# connect to it.
# no_serve_automatically = false

# If true, bypass checking for secure ownership of the
# socket_path.  This is not recommended on a multi-user
# system, but is useful for example when running the
# server inside a WSL container but with the socket
# on the host NTFS volume.
# skip_permissions_check = false

Connecting into Windows Subsystem for Linux

Inside your WSL instance, configure wezterm.toml with this snippet:

[[unix_domains]]
name = "wsl"
# Override the default path to match the default on the host win32
# filesystem.  This will allow the host to connect into the WSL
# container.
socket_path = "/mnt/c/Users/USERNAME/.local/share/wezterm/sock"
# NTFS permissions will always be "wrong", so skip that check
skip_permissions_check = true

In the host win32 configuration, use this snippet:

[[unix_domains]]
name = "wsl"
connect_automatically = true
serve_command = ["wsl", "wezterm", "start", "--daemonize", "--front-end", "MuxServer"]

Now when you start wezterm you'll be presented with a WSL tab.

You can also set connect_automatically = false and use:

$ wezterm connect wsl

to manually connect into your WSL instance.

TLS Domains

Notice: TLS domains require external PKI infrastructure to authenticate both the client and the server side with each other. wezterm doesn't provide an easy way to manage this at this time.

A connection to a multiplexer made via a TLS encrypted TCP connection is referred to as a TLS Domain. Configuring a TLS Domain is currently a bit awkward and requires mutual certificate-based authentication of both ends of the connection. There are no instructions on how to set up the certificates at this time, but this will be expanded as the user experience around this feature is fleshed out.

Requirements

You provide a PKI infrastructure that can generate:

• A certificate for the host with the CN set to the hostname
• A certificate for the client with the CN set to the unixname of the connecting user. The server MUST also be running with the $USER environment variable set to that unixname.
• The CA/chain of certificates must be available to verify those certificates on both sides of the TLS session.
• Guard the user certificate and key carefully as it is the sole means of authenticating the client and will allow execution of arbitrary commands on the server as that user.

Configuring the client

For each server that you wish to connect to, add a client section like this:

[[tls_clients]]
name = "server.name"
# The host:port for the remote host
remote_address = "server.hostname:8080"
# The client private key for your user.  Guard this carefully as
# posession of this secret allows executing commands as you on
# the remote host!  The subject COMMONNAME (or CN) must match
# the USER environment variable that the server side runs as
# otherwise the connection will be rejected.
pem_private_key = "/secure/wez.key"
# The public certificate that corresponds to `pem_private_key`
pem_cert = "/secure/wez.pem"

# A CA file or bundle to help verify certificates
pem_ca = "/secure/ca.pem"
# A list of CA files or directories containing CA files that will
# also be used to verify certificates.
pem_root_certs = ["/secure/trusted-certs"]
connect_automatically = true

Configuring the server

[[tls_servers]]
# The host:port combination on which the server will listen
# for connections
bind_address = "server.hostname:8080"
# The server private key
pem_private_key = "/secure/server.key"
# The public certificate that corresponds to the `pem_private_key`.
# The subject COMMONNAME (or CN) must match the hostname used
# by the client to connect to the server, or the client will
# refuse to connect.
pem_cert = "/secure/server.pem"

# A CA file or bundle to help verify certificates
pem_ca = "/secure/ca.pem"
# A list of CA files or directories containing CA files that will
# also be used to verify certificates.
pem_root_certs = ["/secure/trusted-certs"]

Starting the server

At this time, wezterm doesn't provide a convenient way to automatically start the server, so you will need to manually log in to the server host and start it up:

$ wezterm start --front-end MuxServer --daemonize