<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/multiplexing.md - fork/wezterm @ termwiz-0.23.1</title>
<meta name="description" content="docs/multiplexing.md in fork/wezterm at termwiz-0.23.1.">
<meta property="og:title" content="docs/multiplexing.md - fork/wezterm @ termwiz-0.23.1">
<meta property="og:description" content="docs/multiplexing.md in fork/wezterm at termwiz-0.23.1.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="termwiz-0.23.1" data-tip="7053748e4d899e7fc5e202d6f903b052fc78e759">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/wezterm</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/wezterm</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">mozumasu</span><span class="commit-message" data-commit="f1f87df0448830ed66589eb5540bec2d77546576">fix: docs typos</span><span class="snapshot-sha sha" data-commit="f1f87df0448830ed66589eb5540bec2d77546576">f1f87df04</span><time datetime="2024-09-01T21:30:12+09:00" title="2024-09-01 21:30:12 +0900">2024-09-01</time></p>
<header class="topbar"><details class="switcher"><summary>termwiz-0.23.1</summary><div class="menu"><strong>branches</strong><a href="/fork/wezterm/ref/main/">main</a><strong>tags</strong><a href="/fork/wezterm/ref/termiz-0.23.1/">termiz-0.23.1</a><a href="/fork/wezterm/ref/termiz-0.23.2/">termiz-0.23.2</a><a href="/fork/wezterm/ref/termiz-0.23.3/">termiz-0.23.3</a><a href="/fork/wezterm/ref/termwiz-0.23.0/">termwiz-0.23.0</a><a class="current" href="/fork/wezterm/ref/termwiz-0.23.1/">termwiz-0.23.1</a><a href="/fork/wezterm/ref/termwiz-0.23.2/">termwiz-0.23.2</a><a href="/fork/wezterm/ref/termwiz-0.23.3/">termwiz-0.23.3</a><a href="/fork/wezterm/ref/vtparse-0.7.0/">vtparse-0.7.0</a><a class="all" href="/fork/wezterm/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/wezterm/">wezterm</a> / <a href="/fork/wezterm/ref/termwiz-0.23.1/tree/docs/">docs</a> / <span class="cur">multiplexing.md</span></nav>
<span class="view-stats"><span>9.2 KiB</span><span>284 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/b8a55d1805d323ef24f558d45a343cac873f5757/docs/multiplexing.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><p>!!! note
<em>multiplexing is still a young feature and is evolving rapidly.  Your feedback is welcomed!</em></p>
<h2>Multiplexing</h2>
<p>The out-of-the-box experience with <code>wezterm</code> 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 <a href="https://github.com/tmux/tmux/wiki">tmux</a> or <a href="https://en.wikipedia.org/wiki/GNU_Screen">screen</a>.</p>
<p>Multiplexing in <code>wezterm</code> is based around the concept of <em>multiplexing domains</em>;
a domain is a distinct set of windows and tabs.  When wezterm starts up it
creates a default <em>local domain</em> to manage the windows and tabs in the UI, but it
can also be configured to start or connect to additional domains.</p>
<p>Once connected to a domain, <code>wezterm</code> 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.</p>
<p>Key bindings allow you to spawn new tabs in the default local domain,
the domain of the current tab, or a specific numbered domain.</p>
<h2>SSH Domains</h2>
<p><em>wezterm also supports <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/ssh.md">regular ad-hoc ssh connections</a>.
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</em></p>
<p>A connection to a remote wezterm multiplexer made via an ssh connection is
referred to as an <em>SSH domain</em>.  <strong>A compatible version of wezterm must be
installed on the remote system in order to use SSH domains</strong>.
SSH domains are supported on all systems via libssh2.</p>
<p>To configure an SSH domain, place something like the following in
your <code>.wezterm.lua</code> file:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>ssh_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-c>-- This name identifies the domain</a-c>
    <a-v>name</a-v> = <a-s>&#39;my.server&#39;</a-s><a-p>,</a-p>
    <a-c>-- The hostname or address to connect to. Will be used to match settings</a-c>
    <a-c>-- from your ssh config file</a-c>
    <a-v>remote_address</a-v> = <a-s>&#39;192.168.1.1&#39;</a-s><a-p>,</a-p>
    <a-c>-- The username to use on the remote host</a-c>
    <a-v>username</a-v> = <a-s>&#39;wez&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/SshDomain.md">See SshDomain</a> for more information on possible
settings to use with SSH domains.</p>
<p>To connect to the system, run:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> connect my.server</pre>
<p>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 <em>Unix Domains</em> section below.</p>
<p>{{since('20230408-112425-69ae8472')}}</p>
<p>Ssh_domains now auto-populate from your <code>~/.ssh/config</code> file. Each populated host will have both a plain SSH and a multiplexing SSH domain. Plain SSH hosts are defined with a <code>SSH:</code> prefix to their name and multiplexing hosts are defined with a prefix <code>SSHMUX:</code>. For example, to connect to a host named <code>my.server</code> in your <code>~/.ssh/config</code> using a multiplexing domain, run:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> connect SSHMUX:my.server
<a-c># or to spawn into a new tab in an existing wezterm gui instance:</a-c>
<a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> cli spawn <a-co>--domain-name</a-co> SSHMUX:my.server</pre>
<p>To customize this functionality, see the example for <a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/wezterm/default_ssh_domains.md">wezterm.default_ssh_domains()</a></p>
<h2>Unix Domains</h2>
<p>A connection to a multiplexer made via a unix socket is referred to
as a <em>unix domain</em>.  Unix domains are supported on all systems,
<a href="https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/">even Windows</a>
and are a way to connect the native win32 GUI into the Windows Subsystem for Linux (WSL).</p>
<p>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:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-v>name</a-v> = <a-s>&#39;unix&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr>

<a-c>-- This causes `wezterm` to act as though it was started as</a-c>
<a-c>-- `wezterm connect unix` by default, connecting to the unix</a-c>
<a-c>-- domain on startup.</a-c>
<a-c>-- If you prefer to connect manually, leave out this line.</a-c>
<a-v>config</a-v><a-p>.</a-p><a-v>default_gui_startup_args</a-v> = <a-cr>{</a-cr> <a-s>&#39;connect&#39;</a-s><a-p>,</a-p> <a-s>&#39;unix&#39;</a-s> <a-cr>}</a-cr></pre>
<p>If you prefer to connect manually, omit the <code>default_gui_startup_args</code> setting
and then run:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> connect unix</pre>
<p>Note that in earlier versions of wezterm, a <code>connect_automatically</code> domain
option was shown as the way to connect on startup.  Using
<code>default_gui_startup_args</code> is recommended instead as it works more reliably.</p>
<p>The possible configuration values are:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-c>-- The name; must be unique amongst all domains</a-c>
    <a-v>name</a-v> = <a-s>&#39;unix&#39;</a-s><a-p>,</a-p>

    <a-c>-- The path to the socket.  If unspecified, a reasonable default</a-c>
    <a-c>-- value will be computed.</a-c>

    <a-c>-- socket_path = &quot;/some/path&quot;,</a-c>

    <a-c>-- If true, do not attempt to start this server if we try and fail to</a-c>
    <a-c>-- connect to it.</a-c>

    <a-c>-- no_serve_automatically = false,</a-c>

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

    <a-c>-- skip_permissions_check = false,</a-c>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>{{since('20220101-133340-7edc5b5a')}}</p>
<p>It is now possible to specify a <code>proxy_command</code> that will be used
in place of making a direct unix connection.  When <code>proxy_command</code>
is specified, it will be used instead of the optional <code>socket_path</code>.</p>
<p>This example shows a redundant use of <code>nc</code> (netcat) to connect to
the unix socket path on my mac.  This isn't useful on its own,
but may help with the WSL 2 issue mentioned below when translated
to an appropriate invocation of netcat/socat on Windows:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-v>name</a-v> = <a-s>&#39;unix&#39;</a-s><a-p>,</a-p>
    <a-v>proxy_command</a-v> = <a-cr>{</a-cr> <a-s>&#39;nc&#39;</a-s><a-p>,</a-p> <a-s>&#39;-U&#39;</a-s><a-p>,</a-p> <a-s>&#39;/Users/wez/.local/share/wezterm/sock&#39;</a-s> <a-cr>}</a-cr><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>{{since('20220319-142410-0fcdea07')}}</p>
<p>You may now specify the round-trip latency threshold for enabling predictive
local echo using <code>local_echo_threshold_ms</code>. If the measured round-trip latency
between the wezterm client and the server exceeds the specified threshold, the
client will attempt to predict the server's response to key events and echo the
result of that prediction locally without waiting, hence hiding latency to the
user. This option only applies when <code>multiplexing = "WezTerm"</code>.</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-v>name</a-v> = <a-s>&#39;unix&#39;</a-s><a-p>,</a-p>
    <a-v>local_echo_threshold_ms</a-v> = <a-n>10</a-n><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<h3>Connecting into Windows Subsystem for Linux</h3>
<p><em>Note: this only works with WSL 1. <a href="https://github.com/microsoft/WSL/issues/5961">WSL 2 doesn't support AF_UNIX interop</a></em></p>
<p>Inside your WSL instance, configure <code>.wezterm.lua</code> with this snippet:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-v>name</a-v> = <a-s>&#39;wsl&#39;</a-s><a-p>,</a-p>
    <a-c>-- Override the default path to match the default on the host win32</a-c>
    <a-c>-- filesystem.  This will allow the host to connect into the WSL</a-c>
    <a-c>-- container.</a-c>
    <a-v>socket_path</a-v> = <a-s>&#39;/mnt/c/Users/USERNAME/.local/share/wezterm/sock&#39;</a-s><a-p>,</a-p>
    <a-c>-- NTFS permissions will always be &quot;wrong&quot;, so skip that check</a-c>
    <a-v>skip_permissions_check</a-v> = <a-co>true</a-co><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p>In the host win32 configuration, use this snippet:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>unix_domains</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-v>name</a-v> = <a-s>&#39;wsl&#39;</a-s><a-p>,</a-p>
    <a-v>serve_command</a-v> = <a-cr>{</a-cr> <a-s>&#39;wsl&#39;</a-s><a-p>,</a-p> <a-s>&#39;wezterm-mux-server&#39;</a-s><a-p>,</a-p> <a-s>&#39;--daemonize&#39;</a-s> <a-cr>}</a-cr><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr>
<a-v>config</a-v><a-p>.</a-p><a-v>default_gui_startup_args</a-v> = <a-cr>{</a-cr> <a-s>&#39;connect&#39;</a-s><a-p>,</a-p> <a-s>&#39;wsl&#39;</a-s> <a-cr>}</a-cr></pre>
<p>Now when you start wezterm you'll be presented with a WSL tab.</p>
<p>You can also omit <code>default_gui_startup_args</code> and use:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> connect wsl</pre>
<p>to manually connect into your WSL instance.</p>
<h2>TLS Domains</h2>
<p>A connection to a multiplexer made via a <a href="https://en.wikipedia.org/wiki/Transport_Layer_Security">TLS</a>
encrypted TCP connection is referred to as a <em>TLS Domain</em>.</p>
<p>Starting with version <code>20200202-180558-2489abf9</code>, wezterm can bootstrap a TLS
session by performing an initial connection via SSH to start the wezterm
multiplexer on the remote host and securely obtain a key.  Once bootstrapped,
the client will use a TLS protected TCP connection to communicate with the
server.</p>
<h3>Configuring the client</h3>
<p>For each server that you wish to connect to, add a client section like this:</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>tls_clients</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-c>-- A handy alias for this session; you will use `wezterm connect server.name`</a-c>
    <a-c>-- to connect to it.</a-c>
    <a-v>name</a-v> = <a-s>&#39;server.name&#39;</a-s><a-p>,</a-p>
    <a-c>-- The host:port for the remote host</a-c>
    <a-v>remote_address</a-v> = <a-s>&#39;server.hostname:8080&#39;</a-s><a-p>,</a-p>
    <a-c>-- The value can be &quot;user@host:port&quot;; it accepts the same syntax as the</a-c>
    <a-c>-- `wezterm ssh` subcommand.</a-c>
    <a-v>bootstrap_via_ssh</a-v> = <a-s>&#39;server.hostname&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/TlsDomainClient.md">See TlsDomainClient</a> for more information on possible
settings.</p>
<h3>Configuring the server</h3>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>tls_servers</a-v> = <a-cr>{</a-cr>
  <a-cr>{</a-cr>
    <a-c>-- The host:port combination on which the server will listen</a-c>
    <a-c>-- for connections</a-c>
    <a-v>bind_address</a-v> = <a-s>&#39;server.hostname:8080&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr></pre>
<p><a href="/fork/wezterm/ref/termwiz-0.23.1/blob/docs/config/lua/TlsDomainServer.md">See TlsDomainServer</a> for more information on possible
settings.</p>
<h3>Connecting</h3>
<p>On the client, running this will connect to the server, start up
the multiplexer and obtain a certificate for the TLS connection.
A connection window will show the progress and may prompt you for
SSH authentication.  Once the connection has been initiated, wezterm
will automatically reconnect using the certificate it obtained during
bootstrapping if your connection was interrupted and resume your
remote terminal session</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>wezterm</a-pr> connect server.name</pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">!!! note</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">    *multiplexing is still a young feature and is evolving rapidly.  Your feedback is welcomed!*</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"><a-p>##</a-p> <a-tt>Multiplexing</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">The out-of-the-box experience with `wezterm` allows you to multiplex local tabs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">and windows which will persist until they are closed.  With a little extra</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">configuration you can enable local terminal multiplexing with features similar</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">to those in [tmux](https://github.com/tmux/tmux/wiki) or [screen](https://en.wikipedia.org/wiki/GNU_Screen).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">Multiplexing in `wezterm` is based around the concept of *multiplexing domains*;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">a domain is a distinct set of windows and tabs.  When wezterm starts up it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">creates a default *local domain* to manage the windows and tabs in the UI, but it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">can also be configured to start or connect to additional domains.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">Once connected to a domain, `wezterm` can attach its windows and tabs to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">local native UI, providing a more natural experience for interacting with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">the mouse, clipboard and scrollback features of the terminal.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">Key bindings allow you to spawn new tabs in the default local domain,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">the domain of the current tab, or a specific numbered domain.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>##</a-p> <a-tt>SSH Domains</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">*wezterm also supports [regular ad-hoc ssh connections](ssh.md).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">This section of the docs refers to running a wezterm daemon on the remote end</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">of a multiplexing session that uses ssh as a channel*</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">A connection to a remote wezterm multiplexer made via an ssh connection is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">referred to as an *SSH domain*.  **A compatible version of wezterm must be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">installed on the remote system in order to use SSH domains**.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">SSH domains are supported on all systems via libssh2.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">To configure an SSH domain, place something like the following in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">your `.wezterm.lua` file:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>config.</a-p><a-v>ssh_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>    </a-p><a-c>-- This name identifies the domain</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;my.server&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>    </a-p><a-c>-- The hostname or address to connect to. Will be used to match settings</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>    </a-p><a-c>-- from your ssh config file</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>    </a-p><a-v>remote_address</a-v><a-p> = </a-p><a-s>&#39;192.168.1.1&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>    </a-p><a-c>-- The username to use on the remote host</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>    </a-p><a-v>username</a-v><a-p> = </a-p><a-s>&#39;wez&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>[See SshDomain](config/lua/SshDomain.md) for more information on possible</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>settings to use with SSH domains.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>To connect to the system, run:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>$ wezterm connect my.server</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>This will launch an SSH session that connects to the specified address</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>and may pop up authentication dialogs (using SSH keys for auth is</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>strongly recommended!).  Once connected, it will attempt to spawn</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>the wezterm multiplexer daemon on the remote host and connect to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>it via a unix domain socket using a similar mechanism to that</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>described in the *Unix Domains* section below.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>{{since(&#39;20230408-112425-69ae8472&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>Ssh_domains now auto-populate from your `~/.ssh/config` file. Each populated host will have both a plain SSH and a multiplexing SSH domain. Plain SSH hosts are defined with a `SSH:` prefix to their name and multiplexing hosts are defined with a prefix `SSHMUX:`. For example, to connect to a host named `my.server` in your `~/.ssh/config` using a multiplexing domain, run:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>$ wezterm connect SSHMUX:my.server</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p># or to spawn into a new tab in an existing wezterm gui instance:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>$ wezterm cli spawn --domain-name SSHMUX:my.server</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>To customize this functionality, see the example for [wezterm.default_ssh_domains()](config/lua/wezterm/default_ssh_domains.md)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>## </a-p><a-tt>Unix Domains</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>A connection to a multiplexer made via a unix socket is referred to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>as a *unix domain*.  Unix domains are supported on all systems,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>[even Windows](https://devblogs.microsoft.com/commandline/af_unix-comes-to-windows/)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>and are a way to connect the native win32 GUI into the Windows Subsystem for Linux (WSL).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>The bare minimum configuration to enable a unix domain is this, which will</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>spawn a server if needed and then connect the gui to it automatically</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>when wezterm is launched:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;unix&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"><a-p>-- This causes `wezterm` to act as though it was started as</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>-- `wezterm connect unix` by default, connecting to the unix</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>-- domain on startup.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>-- If you prefer to connect manually, leave out this line.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>config.</a-p><a-v>default_gui_startup_args</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;connect&#39;</a-s><a-p>, </a-p><a-s>&#39;unix&#39;</a-s><a-p> </a-p><a-cr>}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>If you prefer to connect manually, omit the `default_gui_startup_args` setting</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>and then run:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>$ wezterm connect unix</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>Note that in earlier versions of wezterm, a `connect_automatically` domain</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>option was shown as the way to connect on startup.  Using</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>`default_gui_startup_args` is recommended instead as it works more reliably.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>The possible configuration values are:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>    </a-p><a-c>-- The name; must be unique amongst all domains</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;unix&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>    </a-p><a-c>-- The path to the socket.  If unspecified, a reasonable default</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>    </a-p><a-c>-- value will be computed.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>    </a-p><a-c>-- socket_path = &quot;/some/path&quot;,</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>    </a-p><a-c>-- If true, do not attempt to start this server if we try and fail to</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>    </a-p><a-c>-- connect to it.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>    </a-p><a-c>-- no_serve_automatically = false,</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>    </a-p><a-c>-- If true, bypass checking for secure ownership of the</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"><a-p>    </a-p><a-c>-- socket_path.  This is not recommended on a multi-user</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>    </a-p><a-c>-- system, but is useful for example when running the</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"><a-p>    </a-p><a-c>-- server inside a WSL container but with the socket</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>    </a-p><a-c>-- on the host NTFS volume.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>    </a-p><a-c>-- skip_permissions_check = false,</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"><a-p>{{since(&#39;20220101-133340-7edc5b5a&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"><a-p>It is now possible to specify a `proxy_command` that will be used</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>in place of making a direct unix connection.  When `proxy_command`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"><a-p>is specified, it will be used instead of the optional `socket_path`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"><a-p>This example shows a redundant use of `nc` (netcat) to connect to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>the unix socket path on my mac.  This isn&#39;t useful on its own,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"><a-p>but may help with the WSL 2 issue mentioned below when translated</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"><a-p>to an appropriate invocation of netcat/socat on Windows:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;unix&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>    </a-p><a-v>proxy_command</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;nc&#39;</a-s><a-p>, </a-p><a-s>&#39;-U&#39;</a-s><a-p>, </a-p><a-s>&#39;/Users/wez/.local/share/wezterm/sock&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"><a-p>{{since(&#39;20220319-142410-0fcdea07&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>You may now specify the round-trip latency threshold for enabling predictive</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>local echo using `local_echo_threshold_ms`. If the measured round-trip latency</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>between the wezterm client and the server exceeds the specified threshold, the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>client will attempt to predict the server&#39;s response to key events and echo the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-p>result of that prediction locally without waiting, hence hiding latency to the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>user. This option only applies when `multiplexing = &quot;WezTerm&quot;`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;unix&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>    </a-p><a-v>local_echo_threshold_ms</a-v><a-p> = </a-p><a-n>10</a-n><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"><a-p>### </a-p><a-tt>Connecting into Windows Subsystem for Linux</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"><a-p>*Note: this only works with WSL 1. [WSL 2 doesn&#39;t support AF_UNIX interop](https://github.com/microsoft/WSL/issues/5961)*</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"><a-p>Inside your WSL instance, configure `.wezterm.lua` with this snippet:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;wsl&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"><a-p>    </a-p><a-c>-- Override the default path to match the default on the host win32</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"><a-p>    </a-p><a-c>-- filesystem.  This will allow the host to connect into the WSL</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"><a-p>    </a-p><a-c>-- container.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"><a-p>    </a-p><a-v>socket_path</a-v><a-p> = </a-p><a-s>&#39;/mnt/c/Users/USERNAME/.local/share/wezterm/sock&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p>    </a-p><a-c>-- NTFS permissions will always be &quot;wrong&quot;, so skip that check</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"><a-p>    </a-p><a-v>skip_permissions_check</a-v><a-p> = </a-p><a-co>true</a-co><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p>In the host win32 configuration, use this snippet:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"><a-p>config.</a-p><a-v>unix_domains</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;wsl&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"><a-p>    </a-p><a-v>serve_command</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;wsl&#39;</a-s><a-p>, </a-p><a-s>&#39;wezterm-mux-server&#39;</a-s><a-p>, </a-p><a-s>&#39;--daemonize&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"><a-p>config.</a-p><a-v>default_gui_startup_args</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;connect&#39;</a-s><a-p>, </a-p><a-s>&#39;wsl&#39;</a-s><a-p> </a-p><a-cr>}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"><a-p>Now when you start wezterm you&#39;ll be presented with a WSL tab.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"><a-p>You can also omit `default_gui_startup_args` and use:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"><a-p>$ wezterm connect wsl</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>to manually connect into your WSL instance.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text"><a-p>## </a-p><a-tt>TLS Domains</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text"><a-p>A connection to a multiplexer made via a [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text"><a-p>encrypted TCP connection is referred to as a *TLS Domain*.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text"><a-p>Starting with version `20200202-180558-2489abf9`, wezterm can bootstrap a TLS</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text"><a-p>session by performing an initial connection via SSH to start the wezterm</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text"><a-p>multiplexer on the remote host and securely obtain a key.  Once bootstrapped,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text"><a-p>the client will use a TLS protected TCP connection to communicate with the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text"><a-p>server.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text"><a-p>### </a-p><a-tt>Configuring the client</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text"><a-p>For each server that you wish to connect to, add a client section like this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text"><a-p>config.</a-p><a-v>tls_clients</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text"><a-p>    </a-p><a-c>-- A handy alias for this session; you will use `wezterm connect server.name`</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text"><a-p>    </a-p><a-c>-- to connect to it.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text"><a-p>    </a-p><a-v>name</a-v><a-p> = </a-p><a-s>&#39;server.name&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text"><a-p>    </a-p><a-c>-- The host:port for the remote host</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text"><a-p>    </a-p><a-v>remote_address</a-v><a-p> = </a-p><a-s>&#39;server.hostname:8080&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text"><a-p>    </a-p><a-c>-- The value can be &quot;user@host:port&quot;; it accepts the same syntax as the</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text"><a-p>    </a-p><a-c>-- `wezterm ssh` subcommand.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text"><a-p>    </a-p><a-v>bootstrap_via_ssh</a-v><a-p> = </a-p><a-s>&#39;server.hostname&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text"><a-p>[See TlsDomainClient](config/lua/TlsDomainClient.md) for more information on possible</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text"><a-p>settings.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text"><a-p>### </a-p><a-tt>Configuring the server</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text"><a-p>config.</a-p><a-v>tls_servers</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L262" href="#L262">262</a><span class="code-text"><a-p>    </a-p><a-c>-- The host:port combination on which the server will listen</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L263" href="#L263">263</a><span class="code-text"><a-p>    </a-p><a-c>-- for connections</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L264" href="#L264">264</a><span class="code-text"><a-p>    </a-p><a-v>bind_address</a-v><a-p> = </a-p><a-s>&#39;server.hostname:8080&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L265" href="#L265">265</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L266" href="#L266">266</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L267" href="#L267">267</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L268" href="#L268">268</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L269" href="#L269">269</a><span class="code-text"><a-p>[See TlsDomainServer](config/lua/TlsDomainServer.md) for more information on possible</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L270" href="#L270">270</a><span class="code-text"><a-p>settings.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L271" href="#L271">271</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L272" href="#L272">272</a><span class="code-text"><a-p>### </a-p><a-tt>Connecting</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L273" href="#L273">273</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L274" href="#L274">274</a><span class="code-text"><a-p>On the client, running this will connect to the server, start up</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L275" href="#L275">275</a><span class="code-text"><a-p>the multiplexer and obtain a certificate for the TLS connection.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L276" href="#L276">276</a><span class="code-text"><a-p>A connection window will show the progress and may prompt you for</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L277" href="#L277">277</a><span class="code-text"><a-p>SSH authentication.  Once the connection has been initiated, wezterm</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L278" href="#L278">278</a><span class="code-text"><a-p>will automatically reconnect using the certificate it obtained during</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L279" href="#L279">279</a><span class="code-text"><a-p>bootstrapping if your connection was interrupted and resume your</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L280" href="#L280">280</a><span class="code-text"><a-p>remote terminal session</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L281" href="#L281">281</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L282" href="#L282">282</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L283" href="#L283">283</a><span class="code-text"><a-p>$ wezterm connect server.name</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L284" href="#L284">284</a><span class="code-text"><a-p>```</a-p></span></span></pre></div></div>
</main>
</body>
</html>
