# MrTerm

A modern SSH, SFTP and RDP client for Windows and Arch Linux / CachyOS. All your servers live in one place and open in tabs: terminals, file transfers and remote desktops.

MrTerm is available in **English** and **German**. It follows your system language by default, and you can change it under **Settings → Language**.

## Download & installation

Get the latest version from the [releases page](https://git.mrblake.cc/MrBlake/MrTerm/releases).

**Windows**
- `MrTerm-Setup-<version>.exe`: installer (recommended)
- `MrTerm-<version>-portable.exe`: portable, runs without installation

**Arch Linux / CachyOS**
- `MrTerm-<version>.pacman`: install with
  ```sh
  sudo pacman -U MrTerm-<version>.pacman
  ```
- `MrTerm-<version>.AppImage`: make it executable (`chmod +x`) and run it

Optional packages on Linux:
```sh
sudo pacman -S freerdp gnome-keyring   # use kwallet instead of gnome-keyring on KDE
```
`freerdp` is needed for RDP connections. `gnome-keyring` or `kwallet` lets MrTerm encrypt your saved passwords and keys.

## Features

- **Hosts**: nested groups, tags, colors, search and Quick Connect (`user@host:port`, `rdp://host`)
- **SSH terminal in tabs**: password, key, SSH agent, keyboard-interactive/2FA, jump hosts (ProxyJump chains), startup command, environment variables, search, zoom and several color schemes
- **SFTP**: two-pane file browser (local ↔ remote), drag & drop, recursive folders, rename, delete, chmod and progress display
- **RDP in a tab** right inside MrTerm (Windows: `mstsc`, Linux: FreeRDP), or in a separate window if you prefer
- **Keychain**: generate Ed25519/ECDSA/RSA keys, import existing ones and copy the public key
- **Docker & Podman**: list a host's containers, open a shell inside a container, follow logs, and start, stop, restart or remove containers, all over SSH
- **Firewall**: view and edit UFW and iptables/ip6tables rules on your servers
- **Port forwarding**: local (-L), remote (-R) and dynamic/SOCKS5 (-D)
- **VPN**: add WireGuard or OpenVPN configurations and assign them to hosts. MrTerm connects the VPN automatically when you open such a host
- **Snippets**: save frequently used commands and send them to a terminal with one click
- **Known hosts**: MrTerm warns you if a server's host key changes
- **History** of recent connections
- **Import** from `~/.ssh/config` and from **Devolutions Remote Desktop Manager** (`.rdm`/XML, JSON or CSV)
- **Backup** export and import
- **7 app themes** (Midnight, Navy, Nord, Dracula, Catppuccin, Forest, Light) plus a custom accent color
- **Encrypted vault** using your operating system's keyring (Windows DPAPI, Linux libsecret/KWallet)
- **App lock** with a password and/or a FIDO2 security key such as a YubiKey. The vault is then additionally encrypted, and it can lock automatically when you're inactive
- **Automatic updates**: MrTerm checks for new versions on startup and can install them for you

## Getting started

1. Click **New host**, enter the address, username and password or key, and click **Save**.
2. Double-click the host to connect. SSH hosts open a terminal, RDP hosts open a remote desktop tab.
3. Right-click a host for more options, such as opening SFTP, duplicating it or copying its address.

For a quick one-off connection, press `Ctrl+Shift+K` and type `user@host` (or `rdp://host`).

## Keyboard shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl+Shift+K` / `Ctrl+Shift+T` | Quick Connect / command palette (outside the terminal also `Ctrl+K`) |
| `Ctrl+Shift+W` | Close tab |
| `Ctrl+Tab` | Next tab |
| `Ctrl+1..9` | Switch to tab |
| `Ctrl+Shift+C` / `Ctrl+Shift+V` | Copy / paste in the terminal |
| `Ctrl+Shift+F` | Search in the terminal |
| `Ctrl` + `+` / `-` / `0` | Font size |
| `Ctrl+Shift+L` | Lock MrTerm |

`Ctrl+W`, `Ctrl+K` and `Ctrl+T` still reach the terminal, so editors like nano work as usual.

## Docker

Right-click an SSH host and choose **Docker containers**, or click **Docker** in the toolbar of an open terminal. MrTerm connects over SSH and shows all containers on that host, with status, ports, CPU and memory.

- **Open shell**: opens a terminal tab inside the container (bash if available, otherwise sh). You can also double-click a running container.
- **Logs**: follows the container's logs live in a terminal tab.
- **Start, stop, restart, delete** from the row buttons or the right-click menu.

Nothing needs to be installed on the server. MrTerm uses the `docker` command (or `podman` if Docker isn't installed). Your SSH user needs permission to run it, which usually means membership in the `docker` group (`sudo usermod -aG docker <user>`). If a password is saved for the host, MrTerm falls back to `sudo` automatically.

## Firewall

Right-click an SSH host and choose **Firewall**, or click **Firewall** in the toolbar of an open terminal. MrTerm supports **UFW** and **iptables/ip6tables**. If a server has both, you can switch between them at the top.

- **UFW**: turn the firewall on or off, change the default policies for incoming and outgoing traffic, and add or delete rules (allow, deny, reject, limit, with port, protocol, source and comment).
- **iptables**: all chains with their rules, the policy of INPUT, FORWARD and OUTPUT, and adding or deleting rules. iptables changes are lost on reboot unless you click **Save permanently** (uses `netfilter-persistent` on Debian/Ubuntu or `/etc/iptables/*.rules` on Arch).
- **Lockout protection**: if you enable UFW without a rule that allows SSH, MrTerm warns you and offers to allow SSH first. Switching a default policy to blocking asks for confirmation.

This needs root privileges. Either log in as root, or save the password of a user with sudo rights on the host.

## VPN

Under **VPN** in the sidebar you can add WireGuard (`.conf`) and OpenVPN (`.ovpn`) configurations. Paste them or load them from a file, then assign hosts, either in the VPN itself or through the *VPN* field of a host.

When you open an assigned host (terminal, SFTP, RDP or port forwarding), MrTerm connects the VPN first if it isn't already connected. You can also connect and disconnect manually. By default, MrTerm disconnects the VPNs it started when you close it.

- **Linux**: uses NetworkManager, so no root password is needed. For OpenVPN, install the plugin with `sudo pacman -S networkmanager-openvpn`.
- **Windows**: WireGuard requires [WireGuard for Windows](https://www.wireguard.com/install/) and asks for administrator permission when connecting. OpenVPN requires the [OpenVPN GUI](https://openvpn.net/community-downloads/).
- OpenVPN certificates and keys must be embedded in the `.ovpn` file.

## App lock

Under **Settings → App lock** you can protect MrTerm with a password, one or more FIDO2 security keys (e.g. YubiKey), or both. Once a method is set up:

- MrTerm starts locked, and your hosts, keys and passwords stay encrypted until you unlock it.
- Lock it any time with the lock icon in the title bar or `Ctrl+Shift+L`, or let it lock automatically after a period of inactivity.
- Open sessions keep running in the background while MrTerm is locked.

Security keys need to support the *hmac-secret* (PRF) extension, which YubiKey 5 and most current FIDO2 keys do. Touching the key is enough, no PIN is needed. On Linux, the key must be accessible to your user. This is the default on Arch/CachyOS.

**Keep in mind:** if you forget the password and lose all registered security keys, your vault cannot be recovered. Setting up a second unlock method is a good idea.

## Updates

MrTerm looks for updates on startup. You can also check manually under **Settings → Updates**. When a new version is available, click **Install now** and MrTerm will download the right package for your system and restart.

## Troubleshooting

- **"Vault not encrypted"** (Linux): install `gnome-keyring` or `kwallet` and restart MrTerm.
- **RDP doesn't work** (Linux): install FreeRDP with `sudo pacman -S freerdp`. Under **Settings → RDP** you can see which client MrTerm uses and choose another one.
- **RDP tab stays empty**: turn off *Show RDP connections as tabs* under **Settings → RDP** to use a separate window instead.

---

## For developers

```bash
npm install
npm start
```
In VS Code terminals, unset `ELECTRON_RUN_AS_NODE` first.

**Building packages**
- Windows: `npm run dist:win` (on Linux, this needs `wine`)
- Arch/CachyOS: `npm run dist:linux`

If the build fails with `EACCES: permission denied`, some files in `node_modules` belong to root. Run `sudo chown -R $USER: node_modules` and don't run npm with `sudo`.

**Publishing a release**: `./scripts/release-all.sh` asks for the version and release notes, commits and pushes the version, builds Windows + Arch/CachyOS and uploads everything to Gitea. It reads the token from `GITEA_TOKEN` or from `.gitea-token`, which is not committed.

**Translations** live in [`src/i18n.js`](src/i18n.js). The English text in the code is the key. To add a language, add a dictionary and list it in `LANGUAGES`.

To regenerate the icons after changing the logo, run `npx electron scripts/make-icons.js`.