232 lines
16 KiB
Markdown
232 lines
16 KiB
Markdown
# 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.
|
|
|
|
[<img src="https://raw.githubusercontent.com/ImranR98/Obtainium/main/assets/graphics/badge_obtainium.png" alt="Get it on Obtainium" height="54">](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22de.mrterm.app%22%2C%22url%22%3A%22https%3A%2F%2Fgit.mrblake.cc%2FMrBlake%2FMrTerm%22%2C%22author%22%3A%22MrBlake%22%2C%22name%22%3A%22MrTerm%22%2C%22overrideSource%22%3A%22Codeberg%22%7D)
|
|
|
|
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.
|
|
|
|
**Android**
|
|
- Install with [Obtainium](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22de.mrterm.app%22%2C%22url%22%3A%22https%3A%2F%2Fgit.mrblake.cc%2FMrBlake%2FMrTerm%22%2C%22author%22%3A%22MrBlake%22%2C%22name%22%3A%22MrTerm%22%2C%22overrideSource%22%3A%22Codeberg%22%7D): tap the badge above on your phone, or add `https://git.mrblake.cc/MrBlake/MrTerm` in Obtainium and choose **Forgejo (Codeberg)** as the source. Obtainium then keeps MrTerm up to date.
|
|
- Or download `MrTerm-<version>.apk` from the releases page and install it directly.
|
|
|
|
## Android app
|
|
|
|
The Android app is made for phones and focuses on what you need on the go:
|
|
|
|
- **Hosts** with groups, search and Quick Connect (`user@host:port`)
|
|
- **SSH terminal** in full screen with an extra key row (Esc, Tab, Ctrl, Alt, arrow keys, `|`, `~` …), pinch-to-zoom and several open sessions
|
|
- **Keys**: generate or import SSH keys and copy the public key
|
|
- **Snippets** you can send to the terminal with one tap
|
|
- **LAN sync** with MrTerm on your computer: pair once, and your hosts, groups and snippets appear on the phone. You choose which passwords and keys are shared
|
|
- **App lock** with a password and fingerprint unlock. The vault is encrypted with a key kept in the Android Keystore
|
|
|
|
RDP, SFTP, port forwarding and VPN are only available in the desktop app.
|
|
|
|
## 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
|
|
- **Network**: configure interfaces, IP addresses, DHCP, gateway, DNS, bonds (LACP), bridges, VLANs and the hostname on Ubuntu and Debian/Proxmox servers, with automatic rollback
|
|
- **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
|
|
- **LAN sync**: keep several MrTerm devices in sync over your local network, end-to-end encrypted and without a server
|
|
- **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
|
|
|
|
## Screenshots
|
|
|
|
| | |
|
|
|---|---|
|
|
|  |  |
|
|
| **SSH terminal** with tabs and quick access to SFTP, Docker, Firewall and Network | **Host settings**: authentication, keys, jump hosts and VPN |
|
|
|  |  |
|
|
| **Docker & Podman** containers with CPU and memory usage | **Firewall** rules for UFW and iptables |
|
|
|  |  |
|
|
| **Network**: interfaces, bonds (LACP), bridges, gateway and DNS | **VPN**: WireGuard and OpenVPN, connected automatically per host |
|
|
|  | |
|
|
| **Settings**: language, app lock, LAN sync and themes | |
|
|
|
|
## 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.
|
|
|
|
## Synchronization between devices
|
|
|
|
Under **Settings → Synchronization**, you can keep several MrTerm installations in sync, for example your desktop and laptop. Devices talk to each other directly in your local network. There is no server or cloud involved.
|
|
|
|
1. Turn on **LAN synchronization** on both devices.
|
|
2. Click **Pair new device** on both devices and select the other one.
|
|
3. Both devices show a 6-digit code. If the codes match, click **Codes match** on both devices.
|
|
4. Choose which **SSH keys, host passwords and VPN configurations** this device may share. Nothing secret is shared unless you select it, and you can change the selection at any time. When you add a new key, password or VPN later, MrTerm asks whether to share it.
|
|
|
|
From then on, hosts, groups, snippets, port forwards, VPNs and known hosts are synchronized automatically whenever both devices are running on the same network. Deletions are synchronized too. If a change was made on both devices, the newest one wins. Device-specific settings such as theme, language and app lock stay local.
|
|
|
|
**Security:** pairing uses an X25519 key exchange confirmed by the matching code, so another device on the network can't intercept it. Every sync connection is mutually authenticated and encrypted with AES-256-GCM, using a new key for each session.
|
|
|
|
**Firewall:** devices find each other on UDP port 47811 and sync on TCP port 47812. **CachyOS enables the UFW firewall by default**, so run this once on CachyOS (and on any other Linux with UFW enabled):
|
|
|
|
```sh
|
|
sudo ufw allow 47811/udp
|
|
sudo ufw allow 47812/tcp
|
|
```
|
|
|
|
MrTerm shows these commands automatically when it detects CachyOS, UFW or firewalld. Windows asks for permission the first time. If devices can't find each other, you can also add one by its IP address.
|
|
|
|
## 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.
|
|
|
|
UFW rules can only be viewed and added while UFW is enabled.
|
|
|
|
This needs root privileges. Either log in as root, or save the password of a user with sudo rights on the host.
|
|
|
|
## Network
|
|
|
|
Right-click an SSH host and choose **Network**, or click **Network** in the terminal toolbar. MrTerm shows every interface with its state, MAC address, MTU and IP addresses. Bonds also show their mode, LACP rate and the status of each member. The default gateway, DNS servers and hostname appear at the top.
|
|
|
|
On **Ubuntu (netplan)** and **Debian/Proxmox (ifupdown)** you can also edit the configuration:
|
|
|
|
- **Per interface**: DHCP or static IPv4 addresses, gateway, DNS servers and search domains, IPv6 (SLAAC, DHCPv6, static or disabled) and MTU
|
|
- **Bonds** with any mode, including **802.3ad (LACP)** with LACP rate, hash policy and MII monitoring
|
|
- **Bridges** (e.g. Proxmox `vmbr`) and **VLANs**, which you can also create and delete
|
|
- **Hostname** and, if not managed by systemd-resolved, `/etc/resolv.conf`
|
|
- **Config files**: edit the netplan files, `/etc/network/interfaces` or `/etc/hosts` directly
|
|
|
|
**Automatic rollback:** before applying a change, MrTerm backs up the configuration and checks the new one. After applying it, MrTerm opens a new SSH connection to confirm the server is still reachable. If that doesn't work within 90 seconds, the server restores the previous configuration by itself, so a wrong IP address won't lock you out. If your change affects the address MrTerm connects to, enter the new address in the confirmation dialog.
|
|
|
|
On Ubuntu, MrTerm writes the complete netplan configuration to `/etc/netplan/90-mrterm.yaml` and renames the previous files to `*.yaml.mrterm-off`. On Debian/Proxmox, only the changed interfaces are rewritten, and all other lines (such as `post-up` or `bridge-fd`) are kept.
|
|
|
|
Root privileges are required, the same as for the firewall.
|
|
|
|
## 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`.
|
|
|
|
**Android app** (`mobile/`): Capacitor with [capacitor-nodejs](https://github.com/hampoelz/Capacitor-NodeJS). The phone runs the same Node modules as the desktop app (`src/main/ssh.js`, `store.js`, `sync.js` …), bundled with esbuild; the phone UI lives in `mobile/web/`.
|
|
```bash
|
|
cd mobile
|
|
node build.js --setup # once: downloads the Node.js plugin (checksum-verified) and installs dependencies
|
|
node build.js --apk # builds signed APKs into dist/ (needs JDK 21 + Android SDK, see JAVA_HOME / ANDROID_HOME)
|
|
../node_modules/.bin/electron dev/electron-dev.js # try the phone UI on the desktop (after node build.js)
|
|
```
|
|
APKs are signed with `mobile/android/keystore.properties` and the keystore it points to. Both are not committed. Keep a backup, because Android only installs updates signed with the same key.
|
|
|
|
**Publishing a release**: `./scripts/release-all.sh` asks for the version and release notes, commits and pushes the version, builds Windows + Arch/CachyOS + Android 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`.
|