Launch Configuration

Configure default programs, domains, and launch menu in WezTerm

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'

Or use a tilde path:

config.default_cwd = '~/projects'

Launch Menu

The launch menu provides quick access to different shells and programs:

config.launch_menu = {
  {
    label = 'Bash',
    args = { 'bash', '-l' },
  },
  {
    label = 'PowerShell',
    args = { 'pwsh.exe', '-NoLogo' },
  },
  {
    label = 'Top',
    args = { 'top' },
  },
}

Platform-Specific Launch Menus

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 = '~',
  },
}

WezTerm automatically detects installed WSL distributions:

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'

Or connect to a multiplexer on startup:

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

• SSH Feature
• Multiplexing
• CLI Start Command