Installing Wezterm on a Raspberry Pi / Linux server

Wezterm is awesome. It’s incredibly feature rich and offers a very low level of access for configuration compared to many terminal emulators. Wez is also a very kind, easy going and patient maintainer. So it just feels good to be using and supporting his work. It’s also cross platform, meaning a) if I ever do need to work on another OS, my terminal won’t feel foreign to me and b) the inbuilt multiplexer is of huge advantage when working remotely on other machines.

I used to use tmux, but having a multiplexer built directly into the terminal offers excellent configurability (also because Wezterm boasts this as it is) and of course seamless integration by default. It’s also very stable. I’m yet to encounter any bugs on the multiplexer side of Wezterm.

Following are the steps to install Wezterm on a Raspberry Pi and to setup your local Wezterm config to allow multiplexing on the Raspberry via SSH. The steps should remain the same for any Debian/Ubuntu based distro at the very least.

1. Install Wezterm on the remote machine

On your remote machine first install Rust if you need to:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

For the Wezterm install itself, the instructions on Wezterm’s website get you most of the way, but they fall short of installing the binaries in $PATH.

The option of installing via the “smaller source tarball” did not work for me (problems with tar.gz uncompressing… a classic), so I went for the full git repo route.

The sudo install... commands are taken from Wezterm’s own deploy script logic, as recommended by Wez himself.

Contrary to the deply script above, I’ve changed the install path in the instructions from /usr/bin to /usr/local/bin, as the general recommendation is to install programs that are not managed by package mangers to /usr/local/bin.

To clone, build and install Wezterm:

mkdir -p ~/.local/src
cd ~/.local/src
git clone --depth=1 --branch=main --recursive https://github.com/wez/wezterm.git
cd wezterm
git submodule update --init --recursive
./get-deps
cargo build --release
cd target/release
mkdir -p /usr/local/bin /etc/profile.d
sudo install -Dm755 assets/open-wezterm-here wezterm wezterm-gui wezterm-mux-server strip-ansi-escapes -t /usr/local/bin
sudo install -Dm644 assets/shell-integration/* -t /etc/profile.d
sudo install -Dm644 assets/shell-completion/zsh /usr/local/share/zsh/site-functions/_wezterm
sudo install -Dm644 assets/shell-completion/bash /etc/bash_completion.d/wezterm

Now which wezterm should return /usr/bin/wezterm.

2. Setup multiplexing over SSH

Here is the page for multiplexing on the Wezterm website.

You don’t need to configure anything at all on the remote machine / server side.

It’s in your local (client) side (i.e your personal computer) where you edit your wezterm.lua config file to include the details of your remote machine.

Which will look along the lines of this:

config.ssh_domains = {
  {
    -- This name identifies the domain
    name = 'my.server',
    -- The hostname or address to connect to. Will be used to match settings
    -- from your ssh config file
    remote_address = '192.168.1.1',
    -- The username to use on the remote host
    username = 'wez',
  },
}

So in the case of my Raspberry Pi, it looks like this (username is the name of your user on the remote machine):

config.ssh_domains = {
  {
    name = 'raspi',
    remote_address = 'rpi.local',
    username = 'tjex',
  },
}

Now on your local machine, you can execute wezterm connect <your-server-name> (e.g. wezterm connect raspi) and Wezterm will open a new window and connect to the remote machine via SSH.

Once a connection is established, a mux session will be started on the remote machine.

This means that when you close or exit your terminal session, or the connection is broken, you can just reconnect with wezterm connect <your-server-name> and continue where you left off.

If the remote machine shuts down though, you will of course not be able to restore the session.