waveterm Documentation

File: README.md Copy Chapter

Wave Terminal

Wave is an open-source, AI-integrated terminal for macOS, Linux, and Windows. It works with any AI model. Bring your own API keys for OpenAI, Claude, or Gemini, or run local models via Ollama and LM Studio. No accounts required.

Wave also supports durable SSH sessions that survive network interruptions and restarts, with automatic reconnection. Edit remote files with a built-in graphical editor and preview files inline without leaving the terminal.

Key Features Copy Chapter

• Wave AI - Context-aware terminal assistant that reads your terminal output, analyzes widgets, and performs file operations
• Durable SSH Sessions - Remote terminal sessions survive connection interruptions, network changes, and Wave restarts with automatic reconnection
• Flexible drag & drop interface to organize terminal blocks, editors, web browsers, and AI assistants
• Built-in editor for editing remote files with syntax highlighting and modern editor features
• Rich file preview system for remote files (markdown, images, video, PDFs, CSVs, directories)
• Quick full-screen toggle for any block - expand terminals, editors, and previews for better visibility, then instantly return to multi-block view
• AI chat widget with support for multiple models (OpenAI, Claude, Azure, Perplexity, Ollama)
• Command Blocks for isolating and monitoring individual commands
• One-click remote connections with full terminal and file system access
• Secure secret storage using native system backends - store API keys and credentials locally, access them across SSH sessions
• Rich customization including tab themes, terminal styles, and background images
• Powerful wsh command system for managing your workspace from the CLI and sharing data between terminal sessions
• Connected file management with wsh file - seamlessly copy and sync files between local and remote SSH hosts

Wave AI Copy Chapter

Wave AI is your context-aware terminal assistant with access to your workspace:

• Terminal Context: Reads terminal output and scrollback for debugging and analysis
• File Operations: Read, write, and edit files with automatic backups and user approval
• CLI Integration: Use wsh ai to pipe output or attach files directly from the command line
• BYOK Support: Bring your own API keys for OpenAI, Claude, Gemini, Azure, and other providers
• Local Models: Run local models with Ollama, LM Studio, and other OpenAI-compatible providers
• Free Beta: Included AI credits while we refine the experience
• Coming Soon: Command execution (with approval)

Learn more in our Wave AI documentation and Wave AI Modes documentation.

Installation Copy Chapter

Wave Terminal works on macOS, Linux, and Windows.

Platform-specific installation instructions can be found here.

You can also install Wave Terminal directly from: www.waveterm.dev/download.

Minimum requirements Copy Section

Wave Terminal runs on the following platforms:

• macOS 11 or later (arm64, x64)
• Windows 10 1809 or later (x64)
• Linux based on glibc-2.28 or later (Debian 10, RHEL 8, Ubuntu 20.04, etc.) (arm64, x64)

The WSH helper runs on the following platforms:

• macOS 11 or later (arm64, x64)
• Windows 10 or later (x64)
• Linux Kernel 2.6.32 or later (x64), Linux Kernel 3.1 or later (arm64)

Roadmap Copy Chapter

Wave is constantly improving! Our roadmap will be continuously updated with our goals for each release. You can find it here.

Want to provide input to our future releases? Connect with us on Discord or open a Feature Request!

Links Copy Chapter

• Homepage — https://www.waveterm.dev
• Download Page — https://www.waveterm.dev/download
• Documentation — https://docs.waveterm.dev
• X — https://x.com/wavetermdev
• Discord Community — https://discord.gg/XfvZ334gwU

Building from Source Copy Chapter

See Building Wave Terminal.

Contributing Copy Chapter

Wave uses GitHub Issues for issue tracking.

Find more information in our Contributions Guide, which includes:

• Ways to contribute
• Contribution guidelines

Sponsoring Wave ❤️ Copy Section

If Wave Terminal is useful to you or your company, consider sponsoring development.

Sponsorship helps support the time spent building and maintaining the project.

• https://github.com/sponsors/wavetermdev

License Copy Chapter

Wave Terminal is licensed under the Apache-2.0 License. For more information on our dependencies, see here.

File: docs/docs/ai-presets.mdx Copy Chapter

sidebar_position: 3.6 id: "ai-presets" title: "AI Presets (Deprecated)" Copy Chapter

:::warning Deprecation Notice
The AI Widget and its presets are being replaced by Wave AI. Please refer to the Wave AI documentation for the latest AI features and configuration options.
:::

Wave's AI widget can be configured to work with various AI providers and models through presets. Presets allow you to define multiple AI configurations and easily switch between them using the dropdown menu in the AI widget.

How AI Presets Work Copy Chapter

AI presets are defined in ~/.config/waveterm/presets/ai.json. You can easily edit this file using:

wsh editconfig presets/ai.json

Each preset defines a complete set of configuration values for the AI widget. When you select a preset from the dropdown menu, those configuration values are applied to the widget. If no preset is selected, the widget uses the default values from settings.json.

Here's a basic example using Claude:

{
  "ai@claude-sonnet": {
    "display:name": "Claude 3 Sonnet",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>"
  }
}

To make a preset your default, add this single line to your settings.json:

{
  "ai:preset": "ai@claude-sonnet"
}

:::info
You can quickly set your default preset using the setconfig command:

wsh setconfig ai:preset=ai@claude-sonnet

This is easier than editing settings.json directly!
:::

Provider-Specific Configurations Copy Chapter

Anthropic (Claude) Copy Section

To use Claude models, create a preset like this:

{
  "ai@claude-sonnet": {
    "display:name": "Claude 3 Sonnet",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>"
  }
}

OpenAI Copy Section

To use OpenAI's models:

{
  "ai@openai-gpt41": {
    "display:name": "GPT-4.1",
    "display:order": 2,
    "ai:*": true,
    "ai:model": "gpt-4.1",
    "ai:apitoken": "<your OpenAI API key>"
  }
}

Local LLMs (Ollama) Copy Section

To connect to a local Ollama instance:

{
  "ai@ollama-llama": {
    "display:name": "Ollama - Llama2",
    "display:order": 3,
    "ai:*": true,
    "ai:baseurl": "http://localhost:11434/v1",
    "ai:name": "llama2",
    "ai:model": "llama2",
    "ai:apitoken": "ollama"
  }
}

Note: The ai:apitoken is required but can be any value as Ollama ignores it. See Ollama OpenAI compatibility docs for more details.

Azure OpenAI Copy Section

To connect to Azure AI services:

{
  "ai@azure-gpt4": {
    "display:name": "Azure GPT-4",
    "display:order": 4,
    "ai:*": true,
    "ai:apitype": "azure",
    "ai:baseurl": "<your Azure AI base URL>",
    "ai:model": "<your model deployment name>",
    "ai:apitoken": "<your Azure API key>"
  }
}

Note: Do not include query parameters or api-version in the ai:baseurl. The ai:model should be your model deployment name in Azure.

Perplexity Copy Section

To use Perplexity's models:

{
  "ai@perplexity-sonar": {
    "display:name": "Perplexity Sonar",
    "display:order": 5,
    "ai:*": true,
    "ai:apitype": "perplexity",
    "ai:model": "llama-3.1-sonar-small-128k-online",
    "ai:apitoken": "<your perplexity API key>"
  }
}

Google (Gemini) Copy Section

To use Google's Gemini models from Google AI Studio:

{
  "[email protected]": {
    "display:name": "Gemini 2.0",
    "display:order": 6,
    "ai:*": true,
    "ai:apitype": "google",
    "ai:model": "gemini-2.0-flash-exp",
    "ai:apitoken": "<your Google AI API key>"
  }
}

OpenRouter Copy Section

To use OpenRouter's models:

{
  "ai@openrouter": {
    "display:name": "OpenRouter (Qwen)",
    "display:order": 7,
    "ai:*": true,
    "ai:model": "qwen/qwen3-next-80b-a3b-thinking",
    "ai:apitoken": "<openrouter-key>",
    "ai:baseurl": "https://openrouter.ai/api/v1"
  }
}

Multiple Presets Example Copy Chapter

You can define multiple presets in your ai.json file:

{
  "ai@claude-sonnet": {
    "display:name": "Claude 3 Sonnet",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>"
  },
  "ai@openai-gpt41": {
    "display:name": "GPT-4.1",
    "display:order": 2,
    "ai:*": true,
    "ai:model": "gpt-4.1",
    "ai:apitoken": "<your OpenAI API key>"
  },
  "ai@ollama-llama": {
    "display:name": "Ollama - Llama2",
    "display:order": 3,
    "ai:*": true,
    "ai:baseurl": "http://localhost:11434/v1",
    "ai:name": "llama2",
    "ai:model": "llama2",
    "ai:apitoken": "ollama"
  },
  "ai@perplexity-sonar": {
    "display:name": "Perplexity Sonar",
    "display:order": 4,
    "ai:*": true,
    "ai:apitype": "perplexity",
    "ai:model": "llama-3.1-sonar-small-128k-online",
    "ai:apitoken": "<your perplexity API key>"
  }
}

The display:order value determines the order in which presets appear in the dropdown menu.

Remember to set your default preset in settings.json:

{
  "ai:preset": "ai@claude-sonnet"
}

Using a Proxy Copy Chapter

If you need to route AI requests through an HTTP proxy, you can add the ai:proxyurl setting to any preset:

{
  "ai@claude-with-proxy": {
    "display:name": "Claude 3 Sonnet (via Proxy)",
    "display:order": 1,
    "ai:*": true,
    "ai:apitype": "anthropic",
    "ai:model": "claude-3-5-sonnet-latest",
    "ai:apitoken": "<your anthropic API key>",
    "ai:proxyurl": "http://proxy.example.com:8080"
  }
}

The proxy URL should be in the format http://host:port or https://host:port. This setting works with all AI providers except Wave Cloud AI (the default).

File: docs/docs/config.mdx Copy Chapter

sidebar_position: 3.45 id: "config" title: "Configuration" Copy Chapter

import { Kbd } from "@site/src/components/kbd";
import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext";
import { VersionBadge, DeprecatedBadge } from "@site/src/components/versionbadge";

Wave's configuration files are located at ~/.config/waveterm/.

The main configuration file is settings.json (~/.config/waveterm/settings.json).

The file is structured as a mostly flat JSON file. Instead of using sub-objects we prefer to
use ":" as level separators.

:::info

The easiest way to edit your config files is to use the wsh editconfig command which will open your Wave config file in our built-in preview editor.

wsh editconfig

:::

Configuration Keys Copy Chapter

For reference, this is the current default configuration (v0.14.0):

{
    "ai:preset": "ai@global",
    "ai:model": "gpt-5-mini",
    "ai:maxtokens": 4000,
    "ai:timeoutms": 60000,
    "app:defaultnewblock": "term",
    "app:confirmquit": true,
    "app:hideaibutton": false,
    "app:disablectrlshiftarrows": false,
    "app:disablectrlshiftdisplay": false,
    "app:focusfollowscursor": "off",
    "autoupdate:enabled": true,
    "autoupdate:installonquit": true,
    "autoupdate:intervalms": 3600000,
    "conn:askbeforewshinstall": true,
    "conn:wshenabled": true,
    "editor:minimapenabled": true,
    "web:defaulturl": "https://github.com/wavetermdev/waveterm",
    "web:defaultsearch": "https://www.google.com/search?q={query}",
    "window:tilegapsize": 3,
    "window:maxtabcachesize": 10,
    "window:nativetitlebar": true,
    "window:magnifiedblockopacity": 0.6,
    "window:magnifiedblocksize": 0.9,
    "window:magnifiedblockblurprimarypx": 10,
    "window:fullscreenonlaunch": false,
    "window:magnifiedblockblursecondarypx": 2,
    "window:confirmclose": true,
    "window:savelastwindow": true,
    "telemetry:enabled": true,
    "term:bellsound": false,
    "term:bellindicator": false,
    "term:osc52": "always",
    "term:cursor": "block",
    "term:cursorblink": false,
    "term:copyonselect": true,
    "term:durable": false,
    "waveai:showcloudmodes": true,
    "waveai:defaultmode": "waveai@balanced",
    "preview:defaultsort": "name"
}

:::warning

If you installed Wave pre-v0.9.0 your configuration file will be located at
~/.waveterm/config/settings.json. This includes all of the other configuration
files as well: termthemes.json, presets.json, and widgets.json.

:::

Environment Variable Resolution Copy Chapter

To avoid putting secrets directly in config files, Wave supports environment variable resolution using $ENV:VARIABLE_NAME or $ENV:VARIABLE_NAME:fallback syntax. This works for any string value in any config file (settings.json, presets.json, ai.json, etc.).

{
  "ai:apitoken": "$ENV:OPENAI_APIKEY",
  "ai:baseurl": "$ENV:AI_BASEURL:https://api.openai.com/v1"
}

WebBookmarks Configuration Copy Chapter

WebBookmarks allows you to store and manage web links with customizable display preferences. The bookmarks are stored in a JSON file (bookmarks.json) as a key-value map where the key (id) is an arbitrary identifier for the bookmark. By convention, you should start your ids with "bookmark@". In the web widget, you can pull up your bookmarks using

Bookmark Structure Copy Section

Each bookmark follows this structure (only url is required):

{
  "url": "https://example.com",
  "title": "Example Site",
  "iconurl": "https://example.com/custom-icon.png",
  "display:order": 1
}

Fields Copy Section

Example `bookmarks.json` Copy Section

{
  "bookmark@google": {
    "url": "https://www.google.com",
    "title": "Google"
  },
  "bookmark@claude": {
    "url": "https://claude.ai",
    "title": "Claude AI"
  },
  "bookmark@wave": {
    "url": "https://waveterm.dev",
    "title": "Wave Terminal",
    "display:order": -1
  },
  "bookmark@wave-github": {
    "url": "https://github.com/wavetermdev/waveterm",
    "title": "Wave Github",
    "iconurl": "https://github.githubassets.com/favicons/favicon-dark.png"
  },
  "bookmark@chatgpt": {
    "url": "https://chatgpt.com",
    "iconurl": "https://cdn.oaistatic.com/assets/favicon-miwirzcw.ico"
  },
  "bookmark@wave-pulls": {
    "url": "https://github.com/wavetermdev/waveterm/pulls",
    "title": "Wave Pull Requests",
    "iconurl": "https://github.githubassets.com/favicons/favicon-dark.png"
  }
}

Behavior Copy Section

• If iconurl is set, it fetches the icon from the specified URL instead of the site's default favicon.
• Bookmarks are sorted based on display:order (if provided), otherwise by id.
• icon and iconcolor are rarely needed since the default behavior fetches the site's favicon.
• favicons are refreshed every 24-hours

Terminal Theming Copy Chapter

User-defined terminal themes are located in ~/.config/waveterm/termthemes.json.

This JSON file is structured as an object, with each sub-key defining a theme.
Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to
the block's metadata key term:theme. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency).

wsh setmeta this term:theme="default-dark"

Here is an example of defining a full terminal theme. All of the built-in themes are defined here: https://github.com/wavetermdev/waveterm/blob/main/pkg/wconfig/defaultconfig/termthemes.json (if you'd like to add a popular terminal theme, please submit a PR!)

{
  "default-dark": {
    "display:name": "Default Dark",
    "display:order": 1,
    "black": "#757575",
    "red": "#cc685c",
    "green": "#76c266",
    "yellow": "#cbca9b",
    "blue": "#85aacb",
    "magenta": "#cc72ca",
    "cyan": "#74a7cb",
    "white": "#c1c1c1",
    "brightBlack": "#727272",
    "brightRed": "#cc9d97",
    "brightGreen": "#a3dd97",
    "brightYellow": "#cbcaaa",
    "brightBlue": "#9ab6cb",
    "brightMagenta": "#cc8ecb",
    "brightCyan": "#b7b8cb",
    "brightWhite": "#f0f0f0",
    "gray": "#8b918a",
    "cmdtext": "#f0f0f0",
    "foreground": "#c1c1c1",
    "selectionBackground": "",
    "background": "#00000077",
    "cursorAccent": ""
  }
}

:::info

You can easily open the termthemes.json config file by running:

wsh editconfig termthemes.json

:::

Customizable Systemwide Global Hotkey Copy Chapter

Wave allows settings a custom global hotkey to open your most recent window from anywhere in your computer. This has the name "app:globalhotkey" in the settings.json file and takes the form of a series of key names separated by the : character.

Examples Copy Section

As a practical example, suppose you want a value of F5 as your global hotkey. Then you can simply set the value of "app:globalhotkey" to "F5" and reboot Wave to make that your global hotkey.

As a less practical example, suppose you use the combination of the keys Ctrl, Option, and e. Then the value for this keybinding would be "Ctrl:Option:e".

Allowed Key Names Copy Section

We support the following key names:

• Ctrl
• Cmd
• Shift
• Alt
• Option
• Meta
• Super
• Digits (non-numpad) represented by c{Digit0} through c{Digit9}
• Letters a though z
• F keys F1 through F20
• Soft keys Soft1 through Soft4. These are essentially the same as F21 through F24.
• Space represented as either Space or a literal space   
• Enter (This is labeled as return on Mac)
• Tab
• CapsLock
• NumLock
• Backspace (This is labeled as delete on Mac)
• Delete
• Insert
• The arrow keys ArrowUp, ArrowDown, ArrowLeft, and ArrowRight
• Home
• End
• PageUp
• PageDown
• Esc
• Volume controls AudioVolumeUp, AudioVolumeDown, AudioVolumeMute
• Media controls MediaTrackNext, MediaTrackPrevious, MediaPlayPause, and MediaStop
• PrintScreen
• Numpad keys represented by c{Numpad0} through c{Numpad9}
• The numpad decimal represented by Decimal
• The numpad plus/add represented by Add
• The numpad minus/subtract represented by Subtract
• The numpad star/multiply represented by Multiply
• The numpad slash/divide represented by Divide

File: docs/docs/connections.mdx Copy Chapter

sidebar_position: 3.1 id: "connections" title: "Connections" Copy Chapter

import { VersionBadge } from "@site/src/components/versionbadge";

Connections

Wave allows users to connect to various machines and unify them together in a way that preserves the unique behavior of each. At the moment, this extends to SSH remote connections and local WSL connections.

Access a Connection in a Block Copy Chapter

The easiest way to access connections is to click the icon. From there, you can type one of the following to depending on the connection you want:

For SSH Connections:

• [user]@[host]
• [host]
• [user]@[host]:[port]

For WSL Connections:

• wsl://<distribution name>

Alternatively, if the connection already exists in the dropdown list, you can either click it or navigate to it with arrow keys and press enter to connect.

Different Types of Connections Copy Chapter

As there are several different types of connections, not all of the types have access to the same features. SSH and WSL connections can always work in terminal widgets, and if wsh shell extensions are installed, they can also work in preview widgets and the sysinfo widget.

What are wsh Shell Extensions? Copy Chapter

wsh is a small program that helps manage waveterm regardless of which machine you are currently connected to. It is always included on your host machine, but you also have the option to install it when connecting to SSH and WSL Connections. If it is installed on the connection, it is installed at ~/.waveterm/bin/wsh. Then, when wave connects to your connection (and only when wave connects to your connection), the following happens:

• ~/.waveterm/bin is added to your PATH for that individual session. This allows the user to use the wsh command without providing the complete path.
• Several environment variables are injected into the session to make certain tasks with wsh easier. These are listed below.
• The user-defined environment variables in the cmd:env entry ofconnections.json are injected into the session.
• The user-defined initialization scripts located in connections.json are run. For more information on these scripts, see the section below.

If this fails for some reason, Wave will attempt to run without wsh. You will see this indicated by a small `` icon in the block header. For more info on what wsh is capable of, see wsh command. And if you wish to view the source code of wsh, you can find it here.

With wsh installed, you have the ability to view certain widgets from the remote machine as if it were your host, for instance the files and sysinfo widgets. In addition, wsh can be used to influence the widgets across various machines. As a simple example, you can close a widget on the host machine by using the wsh command in a terminal window on a remote machine. For more information on what you can accomplish with wsh, take a look here.

Additional Environment Variables Copy Section

As mentioned above, wsh injects a few environment variables in remote sessions for the user's convenience. These are listed below:

Initialization Scripts

Wave provides you with options for running initialization scripts on your remote machines when connecting to them. These are defined in connections.json and can take either the form of the path of a script or a short script written directly in the file. If multiple scripts are defined, the most specific one relevant to the current shell is applied. The keywords for the scripts are:

Add a New Connection to the Dropdown Copy Chapter

The SSH values that are loaded into the dropdown by default are obtained by parsing the internal config/connections.json file in addition to your ~/.ssh/config and /etc/ssh/ssh_config files. Adding a new connection can be added in a couple ways:

• adding a new Host to one of your ssh config files, typically the ~/.ssh/config file
• adding a new entry in the internal config/connections.json file
• manually typing your connection into the connection box (if this successfully connects, the connection will be added to the internal config/connections.json file)
• use wsh ssh [user]@[host] in your terminal (if this successfully connects, the connection will be added to the internal config/connections.json file)

WSL connections are added by searching the installed WSL distributions as they appear in the Windows Registry. They also exist in the config/connections.json file similarly to SSH connections.

SSH Config Parsing Copy Chapter

At the moment, we are capable of parsing any SSH config file that does not contain the Match keyword. This keyword is incompatible with a library we are using, but we are hoping to fix that soon. While all other valid keywords are parsed, we only support the functionality of a small subset of them at the moment:

Example SSH Config Host Copy Section

For a quick example, a host in your config file may look like:

Host myhost
   User username
   HostName 203.0.113.254
   IdentityFile ~/.ssh/id_rsa
   AddKeysToAgent yes

You would then be able to access this connection with myhost or username@myhost. And if you wanted to manually specify a port such as port 2222, you could do that by either adding Port 2222 to the config file or connecting to username@myhost:2222.

Internal SSH Configuration Copy Chapter

In addition to the regular ssh config file, wave also has its own config file to manage separate variables. These include

SSH Agent Detection Copy Section

Wave resolves the identity agent path in this order:

• If ssh:identityagent (or IdentityAgent in SSH config) is set for the connection, that socket or pipe is used.
• If not set on Windows, Wave falls back to the built-in OpenSSH agent pipe \\.\pipe\openssh-ssh-agent. Ensure the OpenSSH Authentication Agent service is running.
• If not set on macOS/Linux, Wave queries your shell environment for SSH_AUTH_SOCK to detect the agent path automatically.

Example Internal Configurations Copy Section

Here are a couple examples of things you can do using the internal configuration file connections.json:

Hiding a Connection

Suppose you have a connection named github.com in your ~/.ssh/config file that shows up as [email protected] in the connections dropdown. While it does belong in the config file for authentication reasons, it makes no sense to be in the dropdown since it doesn't involve connecting to a remote environment. In that case, you can hide it as in the example below:

{
    <... other connections go here ...>,
    "[email protected]" : {
        "display:hidden": true
    },
    <... other connections go here ...>
}

Moving a Connection

Suppose you have a connection named rarelyused that shows up as myusername@rarelyused:9999 in the connections dropdown. Since it's so rarely used, you would prefer to move it later in the list. In that case, you can move it as in the example below:

{
    <... other connections go here ...>,
    "myusername@rarelyused:9999" : {
        "display:order": 100
    },
    <... other connections go here ...>
}

Theming a Connection

Suppose you have a connection named myhost that shows up as myusername@myhost in the connections dropdown. You use this connection a lot, but you keep getting it mixed up with your local connections. In this case, you can use the internal configuration file to style it differently. For example:

{
    <... other connections go here ...>,
    "myusername@myhost" : {
        "term:theme": "warmyellow",
        "term:fontsize": 16,
        "term:fontfamily": "menlo"
    },
    <... other connections go here ...>
}

This style, font size, and font family will then only apply to the widgets that are using this connection.

Entirely Defined Internally Copy Section

Suppose you want to set up a connection but have no desire to learn the syntax of ~/.ssh/config. In this case, you can entirely define the connection in your connections.json file. For example:

{
    <... other connections go here ...>,
    "myusername@myhost" : {
        "ssh:hostname": "190.0.2.0",
        "ssh:identityfile": ["~/.ssh/myidentityfile"],
        "ssh:identitiesonly": true,
        "ssh:addkeystoagent": true
    },
    <... other connections go here ...>
}

This will create a connection without that connection needing to be in the ~/.ssh/config file. A couple additional options are set as well as an example of how that can be done.

Disabling wsh for a Connection Copy Section

While Wave provides an option disable wsh when first connecting to a remote, there are cases where you may wish to disable it afterward. The easiest way to do this is by editing the connections.json file. Suppose the connection shows up in the dropdown as root@wshless. Then you can disable it manually with the following line:

{
    <... other connections go here ...>,
    "root@wshless" : {
        "conn:enablewsh": false,
    },
    <... other connections go here ...>
}

Note that this same line gets added to your connections.json file automatically when you choose to disable wsh in gui when initially connecting.

Managing Connections with the CLI Copy Chapter

The wsh command gives some commands specifically for interacting with the connections. You can view these here.

Troubleshooting Connections Copy Chapter

Log Files Copy Section

If there are issues with connections, the easiest first step is to enable debugging in a terminal widget that is trying to connect. To do this, click the `` button and hover over the Debug Connection item. From there you can select two log levels, Info and Verbose. After this, debug info will print out to the terminal during the connection.

If this is not sufficient, it is also possible to view the full log file. To do this, you can run the command wsh wavepath log to get the location of a log file.

Known Limitations Copy Section

In the case that there is an error setting up wsh, your connection will still launch without wsh. However, depending on the debug info, there are a few things that can cause this.

Shell Type

Wave is capable of injecting wsh in the following shells:

• bash
• zsh
• pwsh (powershell)
• fish

If the shell is different than those, it is possible the wsh command will not work by default. The easiest way to fix this at the moment is the switch the shell type. This can be done by setting the conn:shellpath value with a path to one of the above shells in the connections.json file for the connection you are trying to use. Alternatively, you can use the chsh command to change the shell in that connection, but this will also take effect outside of wave. Once this is done, restart wave for the changes to take effect.

AllowTcpForwarding in sshd

Some systems have sshd configured to disable TCP forwarding by default. This can be found on the connection in the /etc/ssh/sshd_config file. In that file, search for the line containing AllowTcpForwarding. If this is set to no, it is likely the reason wsh will not work on your connection. In order to get wsh working, set the value for AllowTcpForwarding to either yes or local (they both provide different levels of permission but both work in this case). Then, restart the sshd service with whichever method your remote machine provides. Once that is done, restart wave, so it can reconnect with this change.

File: docs/docs/customization.mdx Copy Chapter

sidebar_position: 3.2 id: "customization" title: "Customization" Copy Chapter

Tab Themes Copy Chapter

Right click on any tab to bring up a menu which allows you to rename the tab and select different backgrounds.

It is also possible to create your own background themes using custom colors, gradients, images and more by editing your backgrounds.json config file. To see how Wave's built-in tab backgrounds are defined, you can check out the default backgrounds.json file.

To apply a tab background to all new tabs by default, set the key tab:background in your Wave Config File to one of the background preset keys (e.g. "bg@ocean-depths"). The available built-in background keys can be found in the default backgrounds.json file.

Terminal Customization Copy Chapter

Terminal Theme

Right click in the header area of any terminal block to bring up a menu which allows you to set a terminal
theme for that terminal.

You can set the default theme for all terminals (which haven't had their theme manually overridden) by editing your settings.json file and adding the key term:theme and setting it to the appropriate key. The keys can be found
in the default termthemes.json file.

If you add your own termthemes.json file in the config directory, you can also add your own custom terminal themes (just follow the same format).

Font Size

From the same context menu you can also change the font-size of the terminal. To change the default font size across all of your (non-overridden) terminals, you can set the config key term:fontsize to the size you want. e.g. { "term:fontsize": 14}.

Font Family

There is no UI to edit your default terminal font family. But, it can be overridden. In your settings.json file you can add the key term:fontfamily and set it to a font that is installed on your local system. If type a font that is not installed, or use a non-monospace font, your terminal will look terrible (don't do that 🙂), delete the key to return to using the default.

Widgets Sidebar Copy Chapter

See Custom Widgets for detailed documentation around changing what appears in your right widget sidebar.

Using widgets.json, you'll be able to remove any default widgets and add widgets of your own. You can fully customize the icons, colors, text, and defaults (like directories, webpages, AI model, remote connection, commands, etc.) of your custom widgets.

You can also suppress the help widgets in the bottom right by setting the config key widget:showhelp to false.

Tab Backgrounds Copy Chapter

Wave supports powerful custom backgrounds for your tabs using images, patterns, gradients, and colors. The quickest way to set an image background is using the wsh setbg command:

# Set an image background with 50% opacity (default)
wsh setbg ~/pictures/background.jpg

# Set a color background (use quotes to prevent # being interpreted as a shell comment)
wsh setbg "#ff0000"          # hex color
wsh setbg forestgreen        # CSS color name

# Adjust opacity
wsh setbg --opacity 0.3 ~/pictures/light-pattern.png
wsh setbg --opacity 0.7      # change only opacity of current background

# Image positioning options
wsh setbg --tile ~/pictures/texture.png          # create tiled pattern
wsh setbg --center ~/pictures/logo.png           # center without scaling
wsh setbg --center --size 200px ~/pictures/logo.png  # center with specific size (px, %, auto)

# Remove background
wsh setbg --clear

You can use any JPEG, PNG, GIF, WebP, or SVG image as your background. The --center option is particularly useful for logos or icons where you want to maintain the original size.

To preview the metadata for any background without applying it, use the --print flag:

wsh setbg --print "#ff0000"

For more advanced customization options including gradients, colors, and saving your own custom backgrounds, check out our Tab Backgrounds documentation.

File: docs/docs/customwidgets.mdx Copy Chapter

sidebar_position: 6 id: "customwidgets" title: "Custom Widgets" Copy Chapter

Custom Widgets

Wave allows users to create their own widgets to uniquely customize their experience for what works for them. While we plan on greatly expanding on this in the future, it is already possible to make some widgets that you can access at the press of a button. All widgets can be created by modifying the <WAVETERM_HOME>/config/widgets.json file. By adding a widget to this file, it is possible to add widgets to the widget bar. By default, the widget bar looks like this:

By adding additional widgets, it is possible to get a widget bar that looks like this:

The Structure of a Widget Copy Chapter

All widgets share a similar structure that roughly looks like the example below:

"<widget name>": {
    "icon": "",
    "label": "",
    "color": "",
    "blockdef": {
        "meta": {
            "view": "term",
            "controller": "cmd",
            "cmd": ""
        }
    }
}

This consists of a couple different parts. First and foremost, each widget has a unique identifying name. The value associated with this name is the outer WidgetConfigType. It is outlined in red below:

This WidgetConfigType is shared between all types of widgets. That is to say, all widgets—regardless of type— will use the same keys for this. The accepted keys are:

Font Awesome provides a ton of useful icons that you can use as a widget icon in your app. At its simplest, you can just provide the icon name and it will be used. For example, the string "house", will provide an icon containing a house. We also allow you to apply a few different styles to your icon by modifying the name as follows:

:::

The other options are part of the inner MetaTSType (outlined in blue in the image). This contains all of the details about how the widget actually works. The valid keys vary with each type of widget. They will be individually explored in more detail below.

Terminal and CLI Widgets Copy Chapter

A terminal widget, or CLI widget, is a widget that simply opens a terminal and runs a CLI command. They tend to look something like the example below:

{
    <... other widgets go here ...>,
    "<widget name>": {
        "icon": "",
        "label": "",
        "color": "",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": ""
            }
        }
    },
    <... other widgets go here ...>
}

The WidgetConfigType takes the usual options common to all widgets. The MetaTSType can include the keys listed below:

Example Local Shell Widgets Copy Section

If you have multiple shells installed on your machine, there may be times when you want to use a non-default shell. For cases like this, it is easy to create a widget for each.

Suppose you want a widget to launch a fish shell. Once you have fish installed on your system, you can define a widget as

{
    <... other widgets go here ...>,
    "fish" : {
        "icon": "fish",
        "color": "#4abc39",
        "label": "fish",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "term:localshellpath": "/usr/local/bin/fish",
                "term:localshellopts": "-i -l"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a terminal running the fish shell.

:::info
It is possible that fish is not in your path. If this is true, using "fish" as the value of "term:localshellpath" will not work. In these cases, you will need to provide a direct path to it. This is often somewhere like "/usr/local/bin/fish", but it may be different on your system.
:::

If you want to do the same for something like Powershell Core, or pwsh, you can define the widget as

{
    <... other widgets go here ...>,
    "pwsh" : {
        "icon": "rectangle-terminal",
        "color": "#2671be",
        "label": "pwsh",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "term:localshellpath": "pwsh"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a terminal running the pwsh shell.

:::info
It is possible that pwsh is not in your path. If this is true, using "pwsh" as the value of "term:localshellpath" will not work. In these cases, you will need to provide a direct path to it. This could be somewhere like "/usr/local/bin/pwsh" on a Unix system or "C:\\Program Files\\PowerShell\\7\\pwsh.exe" on
Windows. but it may be different on your system. Also note that both pwsh.exe and pwsh work on Windows, but only pwsh works on Unix systems.
:::

Example Remote Shell Widgets Copy Section

If you want to open a terminal widget for a particular connection (SSH or WSL), you can use the connection meta key. The connection key's value should match connections.json (or what's in your connections dropdown menu). Note that you should only use the canonical name (do not use any custom "display:name" that you've set). For WSL that might look like wsl://Ubuntu, and for SSH connections that might look like user@remotehostname.

{
	<... other widgets go here ...>,
	"remote-term": {
		"icon": "rectangle-terminal",
		"label": "remote",
		"blockdef": {
			"meta": {
				"view": "term",
				"controller": "shell",
				"connection": "<connection>"
			}
		}
	},
	<... other widgets go here ...>
}

Example Cmd Widgets Copy Section

Here are a few simple cmd widgets to serve as examples.

Suppose I want a widget that will run speedtest-go when opened. Then, I can define a widget as

{
    <... other widgets go here ...>,
    "speedtest" : {
        "icon": "gauge-high",
        "label": "speed",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": "speedtest-go --unix",
                "cmd:clearonstart": true
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a terminal running the speedtest-go --unix command.

Using "cmd" for the "controller" is the simplest way to accomplish this. "cmd:clearonstart" isn't necessary, but it makes it so every time the command is run (which can be done by right clicking the header and selecting Force Controller Restart), the previous contents are cleared out.

Now suppose I wanted to run a TUI app, for instance, dua. Well, it turns out that you can more or less do the same thing:

{
    <... other widgets go here ...>,
    "dua" : {
        "icon": "brands@linux",
        "label": "dua",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": "dua"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a terminal running the dua command.

Because this is a TUI app that does not return anything when closed, the "cmd:clearonstart" option doesn't change the behavior, so it has been excluded.

Web Widgets Copy Chapter

Sometimes, it is desireable to open a page directly to a website. That can easily be accomplished by creating a custom "web" widget. They have the following form in general:

{
    <... other widgets go here ...>,
    "<widget name>": {
        "icon": "",
        "label": "",
        "color": "",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": ""
            }
        }
    },
    <... other widgets go here ...>
}

The WidgetConfigType takes the usual options common to all widgets. The MetaTSType can include the keys listed below:

Example Web Widgets Copy Section

Say you want a widget that automatically starts at YouTube and will use YouTube as the home page. This can be done using:

{
    <... other widgets go here ...>,
    "youtube" : {
        "icon": "brands@youtube",
        "label": "youtube",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://youtube.com",
                "pinnedurl": "https://youtube.com"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a web widget on the youtube homepage.

Alternatively, say you want a web widget that opens to github as if it were a bookmark, but will use google as its home page after that. This can easily be done with:

{
    <... other widgets go here ...>,
    "github" : {
        "icon": "brands@github",
        "label": "github",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://github.com",
                "pinnedurl": "https://google.com"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch a web widget on the github homepage.

Sysinfo Widgets Copy Chapter

The Sysinfo Widget is intentionally kept to a very small subset of possible values that we will expand over time. But it is still possible to configure your own version of it—for instance, if you want to load a different plot by default. The general form of this widget is:

{
    <... other widgets go here ...>,
    "<widget name>": {
        "icon": "",
        "label": "",
        "color": "",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": ,
                "sysinfo:type": ,
            }
        }
    },
    <... other widgets go here ...>
}

The WidgetConfigType takes the usual options common to all widgets. The MetaTSType can include the keys listed below:

Example Sysinfo Widgets Copy Section

Suppose you have a build process that lasts 3 minutes and you'd like to be able to see the entire build on the sysinfo graph. Also, you would really like to view both the cpu and memory since both are impacted by this process. In that case, you can set up a widget as follows:

{
    <... other widgets go here ...>,
    "3min-info" : {
        "icon": "circle-3",
        "label": "3mininfo",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": 180,
                "sysinfo:type": "CPU + Mem"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch the CPU and Memory plots by default with 180 seconds of data.

Now, suppose you are fine with the default 100 points (and 100 seconds) but would like to show all of the CPU data when launched. In that case, you can write:

{
    <... other widgets go here ...>,
    "all-cpu" : {
        "icon": "chart-scatter",
        "label": "all-cpu",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "sysinfo:type": "All CPU"
            }
        }
    },
    <... other widgets go here ...>
}

This adds an icon to the widget bar that you can press to launch All CPU plots by default.

Overriding Default Widgets Copy Chapter

Wave ships with 5 default widgets in the widgets bar (terminal, files, web, ai, and sysinfo). You can modify or remove these by overriding their config in widgets.json. The names of the 5 widgets, in order, are:

• defwidget@terminal
• defwidget@files
• defwidget@web
• defwidget@ai
• defwidget@sysinfo

To remove any of them, just set that key to null in your widgets.json file.

To see their definitions, to copy/paste them, or to understand how they work, you can view all of their definitions on GitHub - default widgets.json

File: docs/docs/faq.mdx Copy Chapter

sidebar_position: 101 id: "faq" title: "FAQ" Copy Chapter

import { VersionBadge } from "@site/src/components/versionbadge";

FAQ

How can I see the block numbers? Copy Section

The block numbers will appear when you hold down Ctrl-Shift (and disappear once you release the key combo).

How do I make a remote connection? Copy Section

There is a button in the header. Click the or
and type the [user]@[host] that you wish to connect to.

On Windows, how can I use Git Bash as my default shell? Copy Section

Wave automatically detects Git Bash installations and adds them to the connection dropdown. Simply click the or button in the block header and select "Git Bash" from the list.

Alternatively, you can manually set Git Bash as your default shell by setting the configuration variable term:localshellpath to
the location of the Git Bash "bash.exe" binary. By default it is located at "C:\Program Files\Git\bin\bash.exe".
Just remember in JSON, backslashes need to be escaped. So add this to your settings.json file:

"term:localshellpath": "C:\\Program Files\\Git\\bin\\bash.exe"

Can I use WSH outside of Wave? Copy Section

wsh is an internal CLI for extending control over Wave to the command line, you can learn more about it here. To prevent misuse by other applications, wsh requires an access token provided by Wave to work and will not function outside of the app.

Why does Wave warn me about ARM64 translation when it launches? Copy Chapter

macOS and Windows both have compatibility layers that allow x64 applications to run on ARM computers. This helps more apps run on these systems while developers work to add native ARM support to their applications. However, it comes with significant performance tradeoffs.

To get the best experience using Wave, it is recommended that you uninstall Wave and reinstall the version that is natively compiled for your computer. You can find the right version by consulting our Installation Instructions.

You can disable this warning by setting app:dismissarchitecturewarning=true in your configurations.

How do I join the beta builds of Wave? Copy Chapter

Wave publishes to two channels, latest and beta. If you've installed the app for macOS, Windows, or Linux via DEB or RPM, you can set the following configurations in your settings.json (see Configuration for more info):

"autoupdate:enabled": true,
"autoupdate:channel": "beta"

If you've installed via Snap, you can use the following command:

sudo snap install waveterm --classic --beta

Can I use Wave AI without enabling telemetry? Copy Chapter

brew install --cask wave

winget install CommandLine.Wave

choco install wave

sudo snap install --classic waveterm