<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/lua/ExecDomain.md - fork/wezterm @ termwiz-0.23.3</title>
<meta name="description" content="docs/config/lua/ExecDomain.md in fork/wezterm at termwiz-0.23.3.">
<meta property="og:title" content="docs/config/lua/ExecDomain.md - fork/wezterm @ termwiz-0.23.3">
<meta property="og:description" content="docs/config/lua/ExecDomain.md in fork/wezterm at termwiz-0.23.3.">
<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.3" data-tip="4bf28e253c0167102f07bfc7e7199c13eed98012">
<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">Wez Furlong</span><span class="commit-message" data-commit="f53145fa4c3bd3f39119edcd6956df35f8937717">docs: refine docker execdomain example</span><span class="snapshot-sha sha" data-commit="f53145fa4c3bd3f39119edcd6956df35f8937717">f53145fa4</span><time datetime="2024-06-03T19:43:21-07:00" title="2024-06-03 19:43:21 -0700">2024-06-03</time></p>
<header class="topbar"><details class="switcher"><summary>termwiz-0.23.3</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 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 class="current" 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.3/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/">config</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/lua/">lua</a> / <span class="cur">ExecDomain.md</span></nav>
<span class="view-stats"><span>6.9 KiB</span><span>237 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/146146a0dd64f397f690449bd59e88465bb998e2/docs/config/lua/ExecDomain.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"><h1>ExecDomain</h1>
<p>{{since('20220807-113146-c2fee766')}}</p>
<p>An <code>ExecDomain</code> defines a local-execution multiplexer domain. In simple terms,
rather than directly executing the requested program, an <code>ExecDomain</code> allows
you wrap up that command invocation by passing it through some other process.</p>
<p>For example, if you wanted to make it more convenient to work with tabs and
panes inside a docker container, you might want to define an <code>ExecDomain</code> that
causes the commands to be run via <code>docker exec</code>.  While you could just ask
wezterm to explicitly spawn a command that runs <code>docker exec</code>, you would also
need to adjust the default key assignments for splitting panes to know about
that preference.  Using an <code>ExecDomain</code> allows that preference to be associated
with the pane so that things work more intuitively.</p>
<h2>Defining an ExecDomain</h2>
<p>You must use the <code>wezterm.exec_domain</code> function to define a domain. It accepts
the following parameters:</p>
<pre>wezterm.exec_domain(NAME, FIXUP [, LABEL])
</pre>
<ul>
<li><em>name</em> - uniquely identifies the domain. Must be different from any other multiplexer domains.</li>
<li><em>fixup</em> - a lua function that will be called to <em>fixup</em> the requested command and return the revised command</li>
<li><em>label</em> - optional. Can be either a string to serve as a label in the
<a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/launch.md#the-launcher-menu">Launcher Menu</a>, or a lua function that will
return the label.</li>
</ul>
<h3>fixup</h3>
<p>The simplest fixup function looks like this:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domain</a-f><a-p>(</a-p><a-s>&#39;myname&#39;</a-s><a-p>,</a-p> <a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p>
  <a-k>return</a-k> <a-v>cmd</a-v>
<a-k>end</a-k><a-p>)</a-p></pre>
<p>The <em>cmd</em> parameter is a <a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/SpawnCommand.md">SpawnCommand</a> that contains
information about the command that is to be executed. This will either be
something that the user configured as a key assignment or will be an equivalent
generated in response to a request to spawn a new tab or split a pane.</p>
<p>It is expected that your fixup function will adjust the various fields
of the provided command and then return it.  The adjusted command is
what wezterm will execute in order to satisfy the user's request to
spawn a new program.</p>
<h3>label</h3>
<p>The label is visible in the <a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/launch.md#the-launcher-menu">Launcher Menu</a>.
You may set it a static string or set it to a lua callback.  The default
behavior is equivalent to this callback function definition:</p>
<pre class="language-lua"><a-c>-- domain_name is the same name you used as the first parameter to</a-c>
<a-c>-- wezterm.exec_domain()</a-c>
<a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domains</a-f><a-p>(</a-p><a-v>domain_name</a-v><a-p>,</a-p> <a-v>fixup_func</a-v><a-p>,</a-p> <a-k>function</a-k><a-p>(</a-p><a-v>domain_name</a-v><a-p>)</a-p>
  <a-k>return</a-k> <a-v>domain_name</a-v>
<a-k>end</a-k><a-p>)</a-p></pre>
<p>Using a callback function allows you to produce an amended label
just in time for the launcher menu to be rendered. That is useful
for example to adjust it to represent some status information.
If you were defining an ExecDomain for a docker container or
VM, then you could have the label reflect whether it is currently
running.</p>
<p>Both the static string and the generated string may include escape sequences
that affect the styling of the text. You may wish to use
<a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/wezterm/format.md">wezterm.format()</a> to manage that.</p>
<h2>Example: Running commands in their own systemd scope</h2>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>
<a-k>local</a-k> <a-v>config</a-v> = <a-cr>{}</a-cr>

<a-c>-- Equivalent to POSIX basename(3)</a-c>
<a-c>-- Given &quot;/foo/bar&quot; returns &quot;bar&quot;</a-c>
<a-c>-- Given &quot;c:\\foo\\bar&quot; returns &quot;bar&quot;</a-c>
<a-k>local</a-k> <a-k>function</a-k> <a-f>basename</a-f><a-p>(</a-p><a-v>s</a-v><a-p>)</a-p>
  <a-k>return</a-k> <a-v>string</a-v><a-p>.</a-p><a-f>gsub</a-f><a-p>(</a-p><a-v>s</a-v><a-p>,</a-p> <a-s>&#39;(.*[/\\])(.*)&#39;</a-s><a-p>,</a-p> <a-s>&#39;%2&#39;</a-s><a-p>)</a-p>
<a-k>end</a-k>

<a-v>config</a-v><a-p>.</a-p><a-v>exec_domains</a-v> = <a-cr>{</a-cr>
  <a-c>-- Defines a domain called &quot;scoped&quot; that will run the requested</a-c>
  <a-c>-- command inside its own individual systemd scope.</a-c>
  <a-c>-- This defines a strong boundary for resource control and can</a-c>
  <a-c>-- help to avoid OOMs in one pane causing other panes to be</a-c>
  <a-c>-- killed.</a-c>
  <a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domain</a-f><a-p>(</a-p><a-s>&#39;scoped&#39;</a-s><a-p>,</a-p> <a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p>
    <a-c>-- The &quot;cmd&quot; parameter is a SpawnCommand object.</a-c>
    <a-c>-- You can log it to see what&#39;s inside:</a-c>
    <a-v>wezterm</a-v><a-p>.</a-p><a-f>log_info</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p>

    <a-c>-- Synthesize a human understandable scope name that is</a-c>
    <a-c>-- (reasonably) unique. WEZTERM_PANE is the pane id that</a-c>
    <a-c>-- will be used for the newly spawned pane.</a-c>
    <a-c>-- WEZTERM_UNIX_SOCKET is associated with the wezterm</a-c>
    <a-c>-- process id.</a-c>
    <a-k>local</a-k> <a-v>env</a-v> = <a-v>cmd</a-v><a-p>.</a-p><a-v>set_environment_variables</a-v>
    <a-k>local</a-k> <a-v>ident</a-v> = <a-s>&#39;wezterm-pane-&#39;</a-s>
      <a-o>..</a-o> <a-v>env</a-v><a-p>.</a-p><a-v>WEZTERM_PANE</a-v>
      <a-o>..</a-o> <a-s>&#39;-on-&#39;</a-s>
      <a-o>..</a-o> <a-f>basename</a-f><a-p>(</a-p><a-v>env</a-v><a-p>.</a-p><a-v>WEZTERM_UNIX_SOCKET</a-v><a-p>)</a-p>

    <a-c>-- Generate a new argument array that will launch a</a-c>
    <a-c>-- program via systemd-run</a-c>
    <a-k>local</a-k> <a-v>wrapped</a-v> = <a-cr>{</a-cr>
      <a-s>&#39;/usr/bin/systemd-run&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--user&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--scope&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--description=Shell started by wezterm&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--same-dir&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--collect&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--unit=&#39;</a-s> <a-o>..</a-o> <a-v>ident</a-v><a-p>,</a-p>
    <a-cr>}</a-cr>

    <a-c>-- Append the requested command</a-c>
    <a-c>-- Note that cmd.args may be nil; that indicates that the</a-c>
    <a-c>-- default program should be used. Here we&#39;re using the</a-c>
    <a-c>-- shell defined by the SHELL environment variable.</a-c>
    <a-k>for</a-k> <a-v>_</a-v><a-p>,</a-p> <a-v>arg</a-v> <a-k>in</a-k> <a-f>ipairs</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v> <a-k>or</a-k> <a-cr>{</a-cr> <a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f> <a-s>&#39;SHELL&#39;</a-s> <a-cr>}</a-cr><a-p>)</a-p> <a-k>do</a-k>
      <a-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p><a-v>wrapped</a-v><a-p>,</a-p> <a-v>arg</a-v><a-p>)</a-p>
    <a-k>end</a-k>

    <a-c>-- replace the requested argument array with our new one</a-c>
    <a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v> = <a-v>wrapped</a-v>

    <a-c>-- and return the SpawnCommand that we want to execute</a-c>
    <a-k>return</a-k> <a-v>cmd</a-v>
  <a-k>end</a-k><a-p>),</a-p>
<a-cr>}</a-cr>

<a-c>-- Making the domain the default means that every pane/tab/window</a-c>
<a-c>-- spawned by wezterm will have its own scope</a-c>
<a-v>config</a-v><a-p>.</a-p><a-v>default_domain</a-v> = <a-s>&#39;scoped&#39;</a-s>

<a-k>return</a-k> <a-v>config</a-v></pre>
<h2>Example: docker domains</h2>
<p>This example shows how to add each running docker container as a domain,
so that you can spawn a shell into it and/or split it:</p>
<p>{% raw %}</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>
<a-k>local</a-k> <a-v>config</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-f>config_builder</a-f><a-p>()</a-p>

<a-k>function</a-k> <a-f>docker_list</a-f><a-p>()</a-p>
  <a-k>local</a-k> <a-v>docker_list</a-v> = <a-cr>{}</a-cr>
  <a-k>local</a-k> <a-v>success</a-v><a-p>,</a-p> <a-v>stdout</a-v><a-p>,</a-p> <a-v>stderr</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-f>run_child_process</a-f> <a-cr>{</a-cr>
    <a-s>&#39;docker&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;container&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;ls&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;--format&#39;</a-s><a-p>,</a-p>
    <a-s>&#39;{{.ID}}:{{.Names}}&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr>
  <a-k>for</a-k> <a-v>_</a-v><a-p>,</a-p> <a-v>line</a-v> <a-k>in</a-k> <a-f>ipairs</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>split_by_newlines</a-f><a-p>(</a-p><a-v>stdout</a-v><a-p>))</a-p> <a-k>do</a-k>
    <a-k>local</a-k> <a-v>id</a-v><a-p>,</a-p> <a-v>name</a-v> = <a-v>line</a-v><a-p>:</a-p><a-f>match</a-f> <a-s>&#39;(.-):(.+)&#39;</a-s>
    <a-k>if</a-k> <a-v>id</a-v> <a-k>and</a-k> <a-v>name</a-v> <a-k>then</a-k>
      <a-v>docker_list</a-v><a-p>[</a-p><a-v>id</a-v><a-p>]</a-p> = <a-v>name</a-v>
    <a-k>end</a-k>
  <a-k>end</a-k>
  <a-k>return</a-k> <a-v>docker_list</a-v>
<a-k>end</a-k>

<a-k>function</a-k> <a-f>make_docker_label_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</a-p>
  <a-k>return</a-k> <a-k>function</a-k><a-p>(</a-p><a-v>name</a-v><a-p>)</a-p>
    <a-k>local</a-k> <a-v>success</a-v><a-p>,</a-p> <a-v>stdout</a-v><a-p>,</a-p> <a-v>stderr</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-f>run_child_process</a-f> <a-cr>{</a-cr>
      <a-s>&#39;docker&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;inspect&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;--format&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;{{.State.Running}}&#39;</a-s><a-p>,</a-p>
      <a-v>id</a-v><a-p>,</a-p>
    <a-cr>}</a-cr>
    <a-k>local</a-k> <a-v>running</a-v> = <a-v>stdout</a-v> <a-o>==</a-o> <a-s>&#39;true\n&#39;</a-s>
    <a-k>local</a-k> <a-v>color</a-v> = <a-v>running</a-v> <a-k>and</a-k> <a-s>&#39;Green&#39;</a-s> <a-k>or</a-k> <a-s>&#39;Red&#39;</a-s>
    <a-k>return</a-k> <a-v>wezterm</a-v><a-p>.</a-p><a-f>format</a-f> <a-cr>{</a-cr>
      <a-cr>{</a-cr> <a-v>Foreground</a-v> = <a-cr>{</a-cr> <a-v>AnsiColor</a-v> = <a-v>color</a-v> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
      <a-cr>{</a-cr> <a-v>Text</a-v> = <a-s>&#39;docker container named &#39;</a-s> <a-o>..</a-o> <a-v>name</a-v> <a-cr>}</a-cr><a-p>,</a-p>
    <a-cr>}</a-cr>
  <a-k>end</a-k>
<a-k>end</a-k>

<a-k>function</a-k> <a-f>make_docker_fixup_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</a-p>
  <a-k>return</a-k> <a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p>
    <a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v> = <a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v> <a-k>or</a-k> <a-cr>{</a-cr> <a-s>&#39;/bin/sh&#39;</a-s> <a-cr>}</a-cr>
    <a-k>local</a-k> <a-v>wrapped</a-v> = <a-cr>{</a-cr>
      <a-s>&#39;docker&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;exec&#39;</a-s><a-p>,</a-p>
      <a-s>&#39;-it&#39;</a-s><a-p>,</a-p>
      <a-v>id</a-v><a-p>,</a-p>
    <a-cr>}</a-cr>
    <a-k>for</a-k> <a-v>_</a-v><a-p>,</a-p> <a-v>arg</a-v> <a-k>in</a-k> <a-f>ipairs</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p>)</a-p> <a-k>do</a-k>
      <a-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p><a-v>wrapped</a-v><a-p>,</a-p> <a-v>arg</a-v><a-p>)</a-p>
    <a-k>end</a-k>

    <a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v> = <a-v>wrapped</a-v>
    <a-k>return</a-k> <a-v>cmd</a-v>
  <a-k>end</a-k>
<a-k>end</a-k>

<a-k>function</a-k> <a-f>compute_exec_domains</a-f><a-p>()</a-p>
  <a-k>local</a-k> <a-v>exec_domains</a-v> = <a-cr>{}</a-cr>
  <a-k>for</a-k> <a-v>id</a-v><a-p>,</a-p> <a-v>name</a-v> <a-k>in</a-k> <a-f>pairs</a-f><a-p>(</a-p><a-f>docker_list</a-f><a-p>())</a-p> <a-k>do</a-k>
    <a-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p>
      <a-v>exec_domains</a-v><a-p>,</a-p>
      <a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domain</a-f><a-p>(</a-p>
        <a-s>&#39;docker:&#39;</a-s> <a-o>..</a-o> <a-v>name</a-v><a-p>,</a-p>
        <a-f>make_docker_fixup_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>),</a-p>
        <a-f>make_docker_label_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</a-p>
      <a-p>)</a-p>
    <a-p>)</a-p>
  <a-k>end</a-k>
  <a-k>return</a-k> <a-v>exec_domains</a-v>
<a-k>end</a-k>

<a-v>config</a-v><a-p>.</a-p><a-v>exec_domains</a-v> = <a-f>compute_exec_domains</a-f><a-p>()</a-p>

<a-k>return</a-k> <a-v>config</a-v></pre>
<p>{% endraw %}</p>
<p>With something like the config above, each time the config is reloaded, the
list of available domains will be updated.</p>
<p>Opening the launcher menu will show them and their status and allow you
to launch programs inside those containers.</p>
</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"><a-p>#</a-p> <a-tt>ExecDomain</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">{{since(&#39;20220807-113146-c2fee766&#39;)}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">An `ExecDomain` defines a local-execution multiplexer domain. In simple terms,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">rather than directly executing the requested program, an `ExecDomain` allows</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">you wrap up that command invocation by passing it through some other process.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">For example, if you wanted to make it more convenient to work with tabs and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">panes inside a docker container, you might want to define an `ExecDomain` that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">causes the commands to be run via `docker exec`.  While you could just ask</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">wezterm to explicitly spawn a command that runs `docker exec`, you would also</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">need to adjust the default key assignments for splitting panes to know about</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">that preference.  Using an `ExecDomain` allows that preference to be associated</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">with the pane so that things work more intuitively.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>##</a-p> <a-tt>Defining an ExecDomain</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">You must use the `wezterm.exec_domain` function to define a domain. It accepts</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">the following parameters:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>```</a-p></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>wezterm.exec_domain(NAME, FIXUP [, LABEL])</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>* *name* - uniquely identifies the domain. Must be different from any other multiplexer domains.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>* *fixup* - a lua function that will be called to *fixup* the requested command and return the revised command</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>* *label* - optional. Can be either a string to serve as a label in the</a-p></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-p>  [Launcher Menu](../launch.md#the-launcher-menu), or a lua function that will</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>  return the label.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>### </a-p><a-tt>fixup</a-tt></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"><a-p>The simplest fixup function looks like this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</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="L37" href="#L37">37</a><span class="code-text"><a-p>wezterm.</a-p><a-f>exec_domain</a-f><a-p>(</a-p><a-s>&#39;myname&#39;</a-s><a-p>, </a-p><a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p></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>  </a-p><a-k>return</a-k><a-p> </a-p><a-v>cmd</a-v></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>end)</a-p></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></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></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>The *cmd* parameter is a [SpawnCommand](SpawnCommand.md) that contains</a-p></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>information about the command that is to be executed. This will either be</a-p></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>something that the user configured as a key assignment or will be an equivalent</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>generated in response to a request to spawn a new tab or split a pane.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></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>It is expected that your fixup function will adjust the various fields</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>of the provided command and then return it.  The adjusted command is</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>what wezterm will execute in order to satisfy the user&#39;s request to</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"><a-p>spawn a new program.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></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>### </a-p><a-tt>label</a-tt></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>The label is visible in the [Launcher Menu](../launch.md#the-launcher-menu).</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"><a-p>You may set it a static string or set it to a lua callback.  The default</a-p></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>behavior is equivalent to this callback function definition:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></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><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>-- domain_name is the same name you used as the first parameter to</a-p></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>-- wezterm.exec_domain()</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>wezterm.</a-p><a-f>exec_domains</a-f><a-p>(</a-p><a-v>domain_name</a-v><a-p>, </a-p><a-v>fixup_func</a-v><a-p>, </a-p><a-k>function</a-k><a-p>(</a-p><a-v>domain_name</a-v><a-p>)</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>  </a-p><a-k>return</a-k><a-p> </a-p><a-v>domain_name</a-v></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>end)</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>```</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>Using a callback function allows you to produce an amended label</a-p></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>just in time for the launcher menu to be rendered. That is useful</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"><a-p>for example to adjust it to represent some status information.</a-p></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>If you were defining an ExecDomain for a docker container or</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"><a-p>VM, then you could have the label reflect whether it is currently</a-p></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>running.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></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>Both the static string and the generated string may include escape sequences</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>that affect the styling of the text. You may wish to use</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>[wezterm.format()](wezterm/format.md) to manage that.</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>## </a-p><a-tt>Example: Running commands in their own systemd scope</a-tt></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-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></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>local </a-p><a-v>config</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="L82" href="#L82">82</a><span class="code-text"></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>-- Equivalent to POSIX basename(3)</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>-- Given &quot;/foo/bar&quot; returns &quot;bar&quot;</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"><a-p>-- Given &quot;c:\\foo\\bar&quot; returns &quot;bar&quot;</a-p></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>local </a-p><a-k>function</a-k><a-p> </a-p><a-f>basename</a-f><a-p>(</a-p><a-v>s</a-v><a-p>)</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>  </a-p><a-k>return</a-k><a-p> </a-p><a-v>string</a-v><a-p>.</a-p><a-f>gsub</a-f><a-p>(</a-p><a-v>s</a-v><a-p>, </a-p><a-s>&#39;(.*[/\\])(.*)&#39;</a-s><a-p>, </a-p><a-s>&#39;%2&#39;</a-s><a-p>)</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>end</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>config.</a-p><a-v>exec_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="L91" href="#L91">91</a><span class="code-text"><a-p>  </a-p><a-c>-- Defines a domain called &quot;scoped&quot; that will run the requested</a-c></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-c>-- command inside its own individual systemd scope.</a-c></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-c>-- This defines a strong boundary for resource control and can</a-c></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-c>-- help to avoid OOMs in one pane causing other panes to be</a-c></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><a-c>-- killed.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>  </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domain</a-f><a-p>(</a-p><a-s>&#39;scoped&#39;</a-s><a-p>, </a-p><a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p></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>    </a-p><a-c>-- The &quot;cmd&quot; parameter is a SpawnCommand object.</a-c></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>    </a-p><a-c>-- You can log it to see what&#39;s inside:</a-c></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>    </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>log_info</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>)</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"></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>    </a-p><a-c>-- Synthesize a human understandable scope name that is</a-c></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><a-c>-- (reasonably) unique. WEZTERM_PANE is the pane id that</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>    </a-p><a-c>-- will be used for the newly spawned pane.</a-c></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>    </a-p><a-c>-- WEZTERM_UNIX_SOCKET is associated with the wezterm</a-c></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>    </a-p><a-c>-- process id.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>env</a-v><a-p> = </a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>set_environment_variables</a-v></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-k>local</a-k><a-p> </a-p><a-v>ident</a-v><a-p> = </a-p><a-s>&#39;wezterm-pane-&#39;</a-s></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>      </a-p><a-o>..</a-o><a-p> </a-p><a-v>env</a-v><a-p>.</a-p><a-v>WEZTERM_PANE</a-v></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><a-o>..</a-o><a-p> </a-p><a-s>&#39;-on-&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"><a-p>      </a-p><a-o>..</a-o><a-p> </a-p><a-f>basename</a-f><a-p>(</a-p><a-v>env</a-v><a-p>.</a-p><a-v>WEZTERM_UNIX_SOCKET</a-v><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"></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>    </a-p><a-c>-- Generate a new argument array that will launch a</a-c></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>    </a-p><a-c>-- program via systemd-run</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>wrapped</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="L115" href="#L115">115</a><span class="code-text"><a-p>      </a-p><a-s>&#39;/usr/bin/systemd-run&#39;</a-s><a-p>,</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"><a-p>      </a-p><a-s>&#39;--user&#39;</a-s><a-p>,</a-p></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-s>&#39;--scope&#39;</a-s><a-p>,</a-p></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>      </a-p><a-s>&#39;--description=Shell started by wezterm&#39;</a-s><a-p>,</a-p></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-s>&#39;--same-dir&#39;</a-s><a-p>,</a-p></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-s>&#39;--collect&#39;</a-s><a-p>,</a-p></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-s>&#39;--unit=&#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-v>ident</a-v><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"><a-p>    </a-p><a-cr>}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"></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>-- Append the requested command</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"><a-p>    </a-p><a-c>-- Note that cmd.args may be nil; that indicates that the</a-c></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>-- default program should be used. Here we&#39;re using the</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"><a-p>    </a-p><a-c>-- shell defined by the SHELL environment variable.</a-c></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-k>for</a-k><a-p> </a-p><a-v>_</a-v><a-p>, </a-p><a-v>arg</a-v><a-p> </a-p><a-k>in</a-k><a-p> </a-p><a-f>ipairs</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p> </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>os</a-v><a-p>.</a-p><a-f>getenv</a-f><a-p> </a-p><a-s>&#39;SHELL&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p>) </a-p><a-k>do</a-k></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-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p><a-v>wrapped</a-v><a-p>, </a-p><a-v>arg</a-v><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>    </a-p><a-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>    </a-p><a-c>-- replace the requested argument array with our new one</a-c></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-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p> = </a-p><a-v>wrapped</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></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>-- and return the SpawnCommand that we want to execute</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-k>return</a-k><a-p> </a-p><a-v>cmd</a-v></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-k>end</a-k><a-p>),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"></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>-- Making the domain the default means that every pane/tab/window</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>-- spawned by wezterm will have its own scope</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>config.</a-p><a-v>default_domain</a-v><a-p> = </a-p><a-s>&#39;scoped&#39;</a-s></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>return </a-p><a-v>config</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"></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>## </a-p><a-tt>Example: docker domains</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>This example shows how to add each running docker container as a domain,</a-p></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>so that you can spawn a shell into it and/or split it:</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"></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>{% raw %}</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>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></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>local </a-p><a-v>config</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>config_builder</a-f><a-p>()</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"></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>function </a-p><a-f>docker_list</a-f><a-p>()</a-p></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-k>local</a-k><a-p> </a-p><a-v>docker_list</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="L159" href="#L159">159</a><span class="code-text"><a-p>  </a-p><a-k>local</a-k><a-p> </a-p><a-v>success</a-v><a-p>, </a-p><a-v>stdout</a-v><a-p>, </a-p><a-v>stderr</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>run_child_process</a-f><a-p> </a-p><a-cr>{</a-cr></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-s>&#39;docker&#39;</a-s><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><a-s>&#39;container&#39;</a-s><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><a-s>&#39;ls&#39;</a-s><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"><a-p>    </a-p><a-s>&#39;--format&#39;</a-s><a-p>,</a-p></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>    </a-p><a-s>&#39;{{.ID}}:{{.Names}}&#39;</a-s><a-p>,</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"><a-p>  </a-p><a-cr>}</a-cr></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>  </a-p><a-k>for</a-k><a-p> </a-p><a-v>_</a-v><a-p>, </a-p><a-v>line</a-v><a-p> </a-p><a-k>in</a-k><a-p> </a-p><a-f>ipairs</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>split_by_newlines</a-f><a-p>(</a-p><a-v>stdout</a-v><a-p>)) </a-p><a-k>do</a-k></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>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>id</a-v><a-p>, </a-p><a-v>name</a-v><a-p> = </a-p><a-v>line</a-v><a-p>:</a-p><a-f>match</a-f><a-p> </a-p><a-s>&#39;(.-):(.+)&#39;</a-s></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>    </a-p><a-k>if</a-k><a-p> </a-p><a-v>id</a-v><a-p> </a-p><a-k>and</a-k><a-p> </a-p><a-v>name</a-v><a-p> </a-p><a-k>then</a-k></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>      </a-p><a-v>docker_list</a-v><a-p>[</a-p><a-v>id</a-v><a-p>] = </a-p><a-v>name</a-v></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>    </a-p><a-k>end</a-k></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>  </a-p><a-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"><a-p>  </a-p><a-k>return</a-k><a-p> </a-p><a-v>docker_list</a-v></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>end</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"></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>function </a-p><a-f>make_docker_label_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</a-p></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-k>return</a-k><a-p> </a-p><a-k>function</a-k><a-p>(</a-p><a-v>name</a-v><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-k>local</a-k><a-p> </a-p><a-v>success</a-v><a-p>, </a-p><a-v>stdout</a-v><a-p>, </a-p><a-v>stderr</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>run_child_process</a-f><a-p> </a-p><a-cr>{</a-cr></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-s>&#39;docker&#39;</a-s><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><a-s>&#39;inspect&#39;</a-s><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><a-s>&#39;--format&#39;</a-s><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"><a-p>      </a-p><a-s>&#39;{{.State.Running}}&#39;</a-s><a-p>,</a-p></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-v>id</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</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="L184" href="#L184">184</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>running</a-v><a-p> = </a-p><a-v>stdout</a-v><a-p> </a-p><a-o>==</a-o><a-p> </a-p><a-s>&#39;true\n&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>color</a-v><a-p> = </a-p><a-v>running</a-v><a-p> </a-p><a-k>and</a-k><a-p> </a-p><a-s>&#39;Green&#39;</a-s><a-p> </a-p><a-k>or</a-k><a-p> </a-p><a-s>&#39;Red&#39;</a-s></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>    </a-p><a-k>return</a-k><a-p> </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>format</a-f><a-p> </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-p>      </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Foreground</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>AnsiColor</a-v><a-p> = </a-p><a-v>color</a-v><a-p> </a-p><a-cr>}</a-cr><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="L188" href="#L188">188</a><span class="code-text"><a-p>      </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Text</a-v><a-p> = </a-p><a-s>&#39;docker container named &#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-v>name</a-v><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="L189" href="#L189">189</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="L190" href="#L190">190</a><span class="code-text"><a-p>  </a-p><a-k>end</a-k></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>end</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"></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>function </a-p><a-f>make_docker_fixup_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</a-p></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-k>return</a-k><a-p> </a-p><a-k>function</a-k><a-p>(</a-p><a-v>cmd</a-v><a-p>)</a-p></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>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p> = </a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p> </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{</a-cr><a-p> </a-p><a-s>&#39;/bin/sh&#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="L196" href="#L196">196</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>wrapped</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="L197" href="#L197">197</a><span class="code-text"><a-p>      </a-p><a-s>&#39;docker&#39;</a-s><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-s>&#39;exec&#39;</a-s><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><a-s>&#39;-it&#39;</a-s><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><a-v>id</a-v><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"><a-p>    </a-p><a-cr>}</a-cr></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>    </a-p><a-k>for</a-k><a-p> </a-p><a-v>_</a-v><a-p>, </a-p><a-v>arg</a-v><a-p> </a-p><a-k>in</a-k><a-p> </a-p><a-f>ipairs</a-f><a-p>(</a-p><a-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p>) </a-p><a-k>do</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"><a-p>      </a-p><a-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</a-p><a-v>wrapped</a-v><a-p>, </a-p><a-v>arg</a-v><a-p>)</a-p></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-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"></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-v>cmd</a-v><a-p>.</a-p><a-v>args</a-v><a-p> = </a-p><a-v>wrapped</a-v></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-k>return</a-k><a-p> </a-p><a-v>cmd</a-v></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-k>end</a-k></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>end</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"></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>function </a-p><a-f>compute_exec_domains</a-f><a-p>()</a-p></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><a-k>local</a-k><a-p> </a-p><a-v>exec_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="L213" href="#L213">213</a><span class="code-text"><a-p>  </a-p><a-k>for</a-k><a-p> </a-p><a-v>id</a-v><a-p>, </a-p><a-v>name</a-v><a-p> </a-p><a-k>in</a-k><a-p> </a-p><a-f>pairs</a-f><a-p>(</a-p><a-f>docker_list</a-f><a-p>()) </a-p><a-k>do</a-k></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>    </a-p><a-v>table</a-v><a-p>.</a-p><a-f>insert</a-f><a-p>(</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"><a-p>      </a-p><a-v>exec_domains</a-v><a-p>,</a-p></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>      </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-f>exec_domain</a-f><a-p>(</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"><a-p>        </a-p><a-s>&#39;docker:&#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-v>name</a-v><a-p>,</a-p></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-f>make_docker_fixup_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>),</a-p></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>        </a-p><a-f>make_docker_label_func</a-f><a-p>(</a-p><a-v>id</a-v><a-p>)</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"><a-p>    )</a-p></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>  </a-p><a-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"><a-p>  </a-p><a-k>return</a-k><a-p> </a-p><a-v>exec_domains</a-v></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>end</a-p></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>config.</a-p><a-v>exec_domains</a-v><a-p> = </a-p><a-f>compute_exec_domains</a-f><a-p>()</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text"><a-p>return </a-p><a-v>config</a-v></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>```</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">{% endraw %}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text">With something like the config above, each time the config is reloaded, the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text">list of available domains will be updated.</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">Opening the launcher menu will show them and their status and allow you</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text">to launch programs inside those containers.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text"></span></span></pre></div></div>
</main>
</body>
</html>
