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

The easiest way to access connections is to click the icon. From there, you can either type [user]@[host] for a desired SSH remote or type wsl://<distribution name> for a desired WSL distribution. 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.

What are wsh Shell Extensions?

wsh is a small program that helps manage waveterm regardless of which machine you are currently connected to. In order to not interrupt the normal flow of the remote session, we install it on your remote machine at ~/.waveterm/bin/wsh. Then, when wave connects to your connection (and only when wave connects to your connection), ~/.waveterm/bin is added to your PATH for that individual session. 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.

Add a New Connection to the Dropdown

The SSH values that are loaded into the dropdown by default are obtained by parsing your ~/.ssh/config and /etc/ssh/ssh_config files. Adding a new connection is as simple as adding a new Host to one of these files, typically the ~/.ssh/config file.

WSL values are added by searching the installed WSL distributions as they appear in the Windows Registry.

SSH Config Parsing

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:

Keyword	Description
Host	The pattern to match when attempting to connect via [user]@[host]. We list hosts that do not contain any wildcards characters (*, ?, or !). Even if a host pattern contains wildcards, it will still be parsed when determining the values associated with the keys as usual.
User	The user of the SSH remote connection. This will default to the current user on the local machine if not specified.
Port	The port to connect to the remote on. 22 is the default if not specified.
IdentityFile	This can be specified more than once per host. It gives the path to a private identity file (id_rsa, id_ed25519, id_ecdsa, etc.) that is used to authenticate the connection. Each will be tried in order, and they can be encrypted with a passphrase if desired. If no value is set, the default is to try in order: ~/.ssh/id_rsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519_sk, ~/.ssh/id_dsa.
BatchMode	If set to true, user interaction via password, challenge/response, and publickey passphrase authentication will be disabled. It is set to false by default.
PubkeyAuthentication	(partial) This is used to specify if pubkey authentication should be attempted. It is partially implementented as the unbound and host-bound values simply work the same as the yes value. The default is yes.
PasswordAuthentication	This is used to specify if password authentication should be attempted. The default is yes.
KbdInteractiveAuthentication	This is used to specify if keyboard-interactive authentication should be attempted. The default is yes.
PreferredAuthentications	(partial) Specifies the order the client should attempt to authenticate in. It is partially implemented as it does not support gssapi-with-mic or hostbased authentication. The default is publickey,keyboard-interactive,password
AddKeysToAgent	(partial) This option will automatically add keys and their corresponding passphrase to your running ssh agent if it is enabled. It is partially supported as it can only accept yes and no as valid inputs. Other inputs such as confirm or a time interval will behave the same as no. The default value is no.
ProxyJump	Specifies one or more jump proxies in a comma separated list. Each will be visited sequentially using TCP forwarding before connecting to the desired connection (also using TCP forwarding). It can be set to none to disable the feature.

Example SSH Config Host

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.

Managing Connections with the CLI

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