Overview
WezTerm’s launch configuration controls what programs run when you create new tabs and panes, how multiplexing domains are configured, and what options appear in the launcher menu.
Default Program
Specify the program to run when launching WezTerm:
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.default_prog = { '/bin/zsh', '-l' }
return config
If not specified, WezTerm will use your system’s default shell.
Default Working Directory
Set the initial working directory:
config.default_cwd = wezterm.home_dir .. '/projects'
config.default_cwd = '~/projects'
config.launch_menu = {
{
label = 'Bash',
args = { 'bash', '-l' },
},
{
label = 'PowerShell',
args = { 'pwsh.exe', '-NoLogo' },
},
{
label = 'Top',
args = { 'top' },
},
}
if wezterm.target_triple == 'x86_64-pc-windows-msvc' then
config.launch_menu = {
{ label = 'PowerShell', args = { 'pwsh.exe', '-NoLogo' } },
{ label = 'Command Prompt', args = { 'cmd.exe' } },
{ label = 'Git Bash', args = { 'C:\\Program Files\\Git\\bin\\bash.exe', '-i', '-l' } },
}
elseif wezterm.target_triple == 'x86_64-apple-darwin' then
config.launch_menu = {
{ label = 'Bash', args = { 'bash', '-l' } },
{ label = 'Zsh', args = { 'zsh', '-l' } },
{ label = 'Fish', args = { '/opt/homebrew/bin/fish', '-l' } },
}
end
Multiplexing Domains
Domains enable persistent sessions and remote connections.
Unix Domains
Local persistent sessions using Unix sockets:
config.unix_domains = {
{
name = 'unix',
},
}
config.default_gui_startup_args = { 'connect', 'unix' }
SSH Domains
Remote multiplexing over SSH:
config.ssh_domains = {
{
name = 'devserver',
remote_address = 'dev.example.com',
username = 'myuser',
},
{
name = 'pi',
remote_address = 'raspberrypi.local',
username = 'pi',
},
}
SSH domains automatically appear in the launcher menu.
WSL Domains
Windows Subsystem for Linux integration:
config.wsl_domains = {
{
name = 'WSL:Ubuntu',
distribution = 'Ubuntu',
default_cwd = '~',
},
}
config.default_domain = 'WSL:Ubuntu'
TLS Domains
Secure remote multiplexing:
config.tls_clients = {
{
name = 'server',
remote_address = 'server.example.com:8080',
bootstrap_via_ssh = 'server.example.com',
},
}
Spawn Commands
Define reusable spawn commands:
config.launch_menu = {
{
label = 'Dev Server SSH',
args = { 'ssh', 'dev.example.com' },
cwd = wezterm.home_dir,
},
{
label = 'Local htop',
args = { 'htop' },
},
}
Default Domain
Set which domain to use by default:
config.default_domain = 'WSL:Ubuntu'
config.default_gui_startup_args = { 'connect', 'unix' }
Advanced Configuration
Per-Domain Default Programs
config.ssh_domains = {
{
name = 'devserver',
remote_address = 'dev.example.com',
username = 'myuser',
-- Run tmux on connection
multiplexing = 'None',
default_prog = { 'tmux', 'attach', '-t', 'dev' },
},
}
Environment Variables
Set environment variables for spawned programs:
config.set_environment_variables = {
TERM = 'wezterm',
COLORTERM = 'truecolor',
}
Skip Launcher on Startup
config.skip_close_confirmation_for_processes_named = {
'bash',
'sh',
'zsh',
'fish',
'tmux',
}
Examples
Complete Launch Configuration
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
config.default_prog = { 'zsh', '-l' }
config.default_cwd = '~/projects'
config.launch_menu = {
{ label = 'Zsh', args = { 'zsh', '-l' } },
{ label = 'Bash', args = { 'bash', '-l' } },
{ label = 'Python', args = { 'python3' } },
{ label = 'Htop', args = { 'htop' } },
}
config.ssh_domains = {
{
name = 'production',
remote_address = 'prod.example.com',
username = 'deploy',
},
}
config.unix_domains = {
{ name = 'unix' },
}
return config
See Also