Motty is a native desktop SSH workspace. It is built in Go on
Viva, so it has no Electron runtime, no embedded
browser and no JavaScript layer. One window holds the terminal, files, tunnels,
remote desktops and the assistant.
Why Motty?
✨ Features
🖥 A terminal that keeps up
Real PTY sessions, 256-colour and true-colour output, the alternate screen, 5,000
lines of scrollback, wide and combining characters, mouse reporting, input
methods and window resizing that follows the pty. Synchronized updates (DECSET
2026) keep a full-screen redraw atomic, the kitty keyboard protocol reports
presses, releases and unambiguous Escape/Alt keys, and Windows local shells can
use win32-input-mode. Font ligatures are shaped inside the fixed-pitch grid.
Tabs can be reordered, split horizontally or vertically, moved between windows
and restored without reconnecting.
Choose Settings > General > Tab orientation for horizontal tabs or a vertical
list in the left sidebar. In terminal workspaces, keep the vertical list expanded
or let it collapse to an icon rail that expands on hover without resizing the
terminal. These layout preferences stay on this device.
Group vertical tabs is a separate General setting, off by default. When
enabled, multiple tabs for the same connection target appear under a collapsible
server heading; a single connection stays a standalone tab. Different accounts,
protocols, ports or local shell environments, and split tabs spanning multiple
servers, stay separate. Grouping only changes the vertical list: it never merges
or disconnects sessions, and turning it off or returning to horizontal mode
restores the original order.
Window and terminal toolbar icons can be dragged to the top, either side's
upper or lower group, or either end of the bottom bar. A drop commits on release;
Escape or dropping outside a dock keeps the layout unchanged. Right-click an
icon to move or hide it, customize the toolbar, or restore its default layout.
Settings > General also controls visibility, order and position. Placements
stay on this device, and terminal actions follow the active split. The SFTP
toolbar keeps its separate visibility and ordering settings.
Settings > General > Terminal toolbar > Customize offers small, medium and large
sizes for both side rails and the bottom bar, including relocated window actions.
The choice stays on this device; top-bar icons keep their standard size.
Connection colors remain on tabs and host markers, while terminal, file and
monitor headers use neutral backgrounds.
Search the retained history, open HTTP/HTTPS and OSC 8 links, render
Kitty/iTerm2/SIXEL images, send snippets, broadcast input across a split tab, or
record a session explicitly. The terminal has eleven colour schemes, keyword
highlighting and optional inline command suggestions.
🔑 Hosts and authentication
Host keys are verified against Motty's own known_hosts before credentials are
sent. Authentication covers agent keys, identity files, OpenSSH user
certificates (the -cert.pub companion of a key file is picked up the way
OpenSSH pairs them), PuTTY .ppk files (versions 2 and 3, Argon2id included),
passwords and keyboard-interactive rounds. A round that asks several questions
— for example a password and a one-time code from the same PAM stack — is shown
as one dialog with one field per question. Hosts presenting a certificate
connect without a prompt once their CA is on file as @cert-authority, and an
unknown certificate is asked about with its fingerprint, like any unknown key.
A host can also forward the local ssh-agent to its shells, per host and off by
default.
Hosts can be grouped, tagged, searched and imported from OpenSSH config, PuTTY,
Xshell, MobaXterm, WindTerm, Electerm or Netcatty. TOTP/HOTP seeds can be stored in the
vault and filled automatically. Saved passwords and key passphrases go into an
AES-256-GCM vault, kept under the host they belong to; the vault key lives in the
system secret store, or in a key file beside the vault where there is none (and
in a portable copy).
Electerm and Netcatty imports can save readable SSH passwords with explicit
consent; re-import only fills missing passwords.
🗂 Files without another app
SFTP browsing with multi-select, recursive upload/download, a bounded transfer
queue, resume, cancel/retry, rename, delete, permissions and bookmarks.
Replacing a file stages a partial copy, verifies resumed prefixes and renames
atomically only after a complete synced copy. The previous file stays intact on
failure.
A native editor opens UTF-8 files up to 1 MiB, hashes the remote file before and
after staging, and preserves permissions. Servers without SFTP can use the
built-in SCP fallback. It edits code in a fixed-pitch grid with line numbers,
syntax colors, bracket matching, soft wrap, auto-indent that follows the file's
own tabs or spaces, paired brackets and quotes, Tab/Shift+Tab block indent,
line comment toggling (Cmd/Ctrl+/), line move/copy/delete (Alt+Up/Down,
Shift+Alt+Up/Down, Cmd/Ctrl+Shift+K), find and replace (Cmd/Ctrl+F, Ctrl+H) with
case, whole-word and regular-expression options, and go to line (Ctrl+G).
The panel's more menu can hand the folder it shows to VS Code or Zed through the
editor's own URL scheme. Pick the editor under Settings > Files, which lists
the editors installed on this computer; until one is picked the menu item stays
hidden. A server is opened under the alias your SSH config gives that very host
(same address, user and port), or as user@host; a host reached through a jump
host that only Motty keeps is refused, because the editor's own ssh would not use
it.
The attached file panel can follow the SSH terminal's folder automatically for
Bash and Zsh. Settings > Files also offers a separate, default-off switch for
the terminal to follow file navigation at a ready, empty prompt. See
folder synchronization for safety and startup
compatibility details.
🔀 Forwarding and jump chains
Local, remote, SOCKS5 and HTTP CONNECT rules are loopback-only, persisted and
started explicitly. Tunnels stop with the SSH tab that owns them. Jump routes
verify and authenticate every hop independently. A global outbound SOCKS5/HTTP
proxy can carry the initial connection; each saved network host can inherit it,
force a direct connection, use its own SOCKS5/HTTP proxy, or connect through a
proxy command such as cloudflared access ssh (OpenSSH's ProxyCommand). X11
forwarding validates a per-session fake cookie before replacing it with the local
Xauthority cookie.
🖥 Remote desktops
VNC supports RFB 3.3/3.7/3.8, None and VNC Authentication, Raw/CopyRect/RRE/
Hextile/ZRLE, desktop resize, pointer, keyboard and text clipboard. RDP uses TLS
with NLA preferred and pins the server certificate after an explicit trust
decision; it also copies files to the server (paste them in the remote or drop
them on the picture). Both can connect through an SSH host when the server only listens on
its own loopback. See docs/remote-desktop.md for the
exact limits.
🤖 Assistant and MCP
Ask answers questions with the visible terminal as context. Agent can
also run commands in that terminal, with a risk classification and an approval
gate. In Ask mode the assistant can ask to switch to Agent when a request needs
a tool; approving the switch retries the request in Agent mode, and the choice
is remembered. A run command is shown as the command itself with an accent mark in the
terminal's left margin; Motty hides its capture wrapper and marker from the
screen and from its own command history, though the remote shell's own history
is outside Motty's control. Secrets are redacted
before terminal text reaches a model — key files, assignments, embedded URL
credentials and well-known token formats — and provider keys stay in the vault.
Long conversations send their newest rounds within a fixed budget, so a session
cannot outgrow the model's context. Hovering the last answer shows its token usage
and a copy button, and saved conversations can be renamed.
An optional MCP server exposes the same tools to external agents. It is off by
default, loopback-only, bearer-token protected, and supports observe and ask
modes. motty mcp-serve is the same idea without the window: an agent starts it
over stdio and it works on the hosts you opened to agents, with no port and no
token.
☁️ Backup and sync
Encrypted .mottybak export, plus record-level sync through WebDAV,
S3-compatible storage or a GitHub Gist. Records carry hybrid logical clocks and
90-day deletion tombstones, so computers converge without one overwriting the
other. Tabs, window layout, shortcuts, fonts, key paths and cloud credentials
stay local.
Remote WebDAV and S3 addresses require HTTPS by default. To use a trusted LAN
service over HTTP, check Allow insecure remote HTTP at the bottom of its
configuration form. The connection is unencrypted and authentication details may
be intercepted; the backup file is still encrypted before upload. This choice
stays on this computer.
🚀 Quick start
- Open Hosts and choose New host.
- Enter a name, address and account name.
- Pick authentication: the running agent, a private-key file or the password.
- Connect and compare the host-key fingerprint with the server. Trust it once or
save it.
- The tab opens on the login shell. A server that asks for a one-time code gets
the extra field automatically.
The command palette is Command+Shift+P on macOS and Control+Shift+P
elsewhere. Default shortcuts use Command on macOS and Control on Windows/Linux;
all of them are configurable.
On Windows, choose the local shell from the dropdown in Settings → Terminal
→ Local shell, below Inline suggestions. Motty detects installed shells
such as PowerShell, CMD and Git Bash from PATH and common installation folders,
and lists each installed WSL distribution as its own entry. The file panel
follows a WSL terminal's folder too, through the distribution's \\wsl.localhost
share. Choose the distribution here, rather than typing wsl into PowerShell:
only a shell Motty starts itself can report its folder. The choice stays on this
computer and applies to new or reconnected local terminals.
| Action | macOS | Windows / Linux |
|---|
| Command palette | Command+Shift+P | Control+Shift+P |
| Find in terminal | Command+F | Control+F |
| Command history | Command+Shift+H | Control+Shift+H |
| File panel | Command+Shift+S | Control+Shift+S |
| New window | Command+Shift+N | Control+Shift+N |
📦 Install
Download the package for your platform from the
releases page:
| Platform | Packages |
|---|
| macOS (arm64, amd64) | .dmg, .zip |
| Windows (amd64, arm64) | .exe installer, portable .zip (data kept in motty-data beside motty.exe) |
| Linux (amd64, arm64) | .deb, .tar.gz |
macOS builds are signed and notarized when the release has the credentials.
Windows builds are signed when a certificate is configured. Linux packages are
not signed. AUR and .AppImage are not available yet.
Through a package manager:
brew install --cask t8y2/tap/motty
If Homebrew asks you to trust the tap first, run brew trust t8y2/tap once.
scoop bucket add t8y2 https://github.com/t8y2/scoop-bucket
scoop install t8y2/motty
The cask installs the notarized disk image and is marked as self-updating, so an
installed copy updates itself. Scoop installs the portable copy: its
motty-data folder is persisted across versions and scoop update motty is how
it updates.
If Motty closes unexpectedly
Motty keeps a log and, after an abnormal exit, a crash report in the logs
folder of its data directory: %APPDATA%\motty\logs on Windows,
~/Library/Application Support/motty/logs on macOS, ~/.config/motty/logs on
Linux (motty-data\logs beside the program in a portable copy). Attach
motty.log and the newest crash-*.log to a bug report. When the program
cannot start at all, it says why in a message box and writes the reason to the
log.
If the program disappears and crash.log stays empty, the process was ended by
a native fault (a graphics driver, for instance) before Go could write
anything. On Windows 11 22H2 or later Motty then asks Windows Error Reporting for
a dump in %LOCALAPPDATA%\Motty\CrashDumps; the Application Error event in
Event Viewer (Windows Logs → Application) names the faulting module. To tell
the usual suspects apart, start Motty with VIVA_SOFTWARE_RENDERING=1 (no
graphics driver) or VIVA_ACCESSIBILITY=0 (no UI Automation tree) set. A dump
is a copy of the program's memory: look before you share it.
🛠 Build from source
Requirements:
- Go 1.26 or newer.
- The Viva framework checked out beside this repository as
../viva. Viva is a
separate project with its own licence and is not vendored.
- macOS with Metal and Xcode command-line tools, Windows 10/11, or Linux with
X11.
git clone https://github.com/t8y2/motty
git clone https://github.com/vivaui/viva
cd motty
go run ./cmd/motty
Tests and the headless build:
gofmt -l .
go vet ./...
go test ./...
go test -race ./...
go build -tags vivahead -o /tmp/motty-head ./cmd/motty
python3 tools/headless_drive.py /tmp/motty-home tools/e2e/host_menu_move_e2e.txt
tools/README.md describes the headless driver, fixtures and end-to-end
scripts. Packaging goes through Viva:
cd ../viva
go run ./cmd/viva package -C ../motty --format app,dmg
go run ./cmd/viva package -C ../motty --target linux --arch amd64 --format tar.gz,deb
Development builds
Build and launch one development binary with:
make run
The binary is built with -tags dev, so its window and tray say Motty Dev
and its Dock icon carries a red DEV badge. The logo and wordmark inside the
window are the release ones, so the interface itself looks like what ships and
the running copy is still told apart at a glance. Use make dev to rebuild and
restart when a Go file in this repository or ../viva changes; watch mode needs
fswatch. One-shot mode does not. tools/dev.sh --once is the same entry
point as make run.
Development builds use motty-dev under the platform's configuration directory,
separate from the release build's unchanged motty directory. Their vault keys
also use a separate system-secret namespace. The default copies can run side by
side without upgrading each other's databases. When an unused default development
profile finds release data, its first-run dialog offers Import copy or
Start empty. Import reads the release profile without changing it, copies
hosts, shared settings and trusted keys, and optionally re-encrypts saved
passwords under the development key. It never copies open sessions or cloud
logins. Closing the dialog postpones the choice; failures stay visible and
unfinished imports can resume without replacing current hosts or passwords.
Existing profiles and explicit MOTTY_DATA_DIR profiles are not auto-imported;
they can still restore an encrypted backup through Backup & sync.
On macOS the standard entry creates or reuses a private local development
signing identity under ~/Library/Application Support/motty/development-signing.
The first access may require one system Keychain authorization. Subsequent
content-different rebuilds reuse that authorization while the same identity and
unlocked Keychain remain available. This does not bypass a locked Keychain, a
changed ACL or an explicit identity change. A signing or verification failure
stops the launch instead of silently running an unsigned build.
Use an explicit certificate without creating the default identity with
MOTTY_DEV_SIGN_IDENTITY='Developer ID Application: …' make run. Use
MOTTY_DEV_SIGN_IDENTITY=none make run only for an intentional unsigned run;
the entry warns that Keychain authorization may repeat. go run ./cmd/motty
is release behaviour, while go run -tags dev ./cmd/motty bypasses the signing
helper and is intended only for diagnosis.
MOTTY_DATA_DIR still overrides the directory. Use disposable data and test
credentials for destructive tests: profiles within one build variant still
share its system-secret namespace. Never point a development build at production
data or configure production cloud sync unless that shared access is intentional.
Portable development builds use motty-dev-data, not motty-data.
Configuration epoch 23 introduces lossless field updates. Compatible additions
to JSON objects no longer require a format bump; unknown fields and records
survive saves, sync and backup restoration. Conflicting edits fail rather than
overwrite unread data. Arrays remain atomic, so incompatible element changes
still require a new epoch. Application writer versions are diagnostic only.
Older epochs (including 19–22) upgrade once; already released older binaries
cannot read epoch 23. Do not edit the database's format number to bypass this
protection. See storage compatibility.
🔐 Security
- Host-key verification happens before any credential is sent.
- Saved passwords and passphrases are stored in an AES-256-GCM vault; its key is
in the system secret store, or in a key file in the data folder where the system
has none: anyone who can copy that folder can read the vault.
- AI provider keys are in the vault. Terminal context is redacted by default, and
agent commands pass through the approval gate.
- The MCP server is off by default, loopback-only and bearer-token protected.
- Motty has no analytics. The optional update check contacts GitHub Releases and
is off by default.
The approval gate is a safety control, not a sandbox. Do not point an agent at a
host where a wrong command is unacceptable.
To report a vulnerability, use GitHub's private vulnerability reporting on the
repository. Please keep credentials, host names and terminal output out of public
issues.
🧱 Architecture
Motty owns SSH, authentication, SFTP, terminal emulation, forwarding,
remote-desktop protocols, persistence and product workflows. Viva owns windowing,
input, text/IME, focus, layout, components and rendering. Reusable desktop
capabilities go into Viva rather than being duplicated here.
| Path | Contents |
|---|
cmd/motty | application entry point, headless mode, MCP bridge and mcp-serve |
internal/sshconn | SSH dialling, host keys, authentication, proxies and jump routes |
internal/term | terminal emulator and parser |
internal/rfb, internal/desktop/vnc | VNC protocol and desktop backend |
internal/rdpcore, internal/desktop/rdp | RDP protocol (MIT-licensed fork) and backend |
internal/sftpclient, internal/scpclient | SFTP and SCP clients |
internal/forward | local, remote, SOCKS5 and HTTP CONNECT forwarding |
internal/workbench | application state, screens, painting and input |
internal/ai | assistant, tools, risk gate and MCP server |
assets, docs, tools | branding, technical notes and development tooling |
website | static documentation site published to motty.page — docs/website.md |
💬 Community
The QQ group, the WeChat group in its Tencent Doc and the Discord server are all
live.
🤝 Contributing
Issues and pull requests are welcome. Start with an issue for a large change so
the approach can be discussed before the code is written.
Comment /claim on an issue to take it: the bot assigns you and posts a
confirmation. Comment /unclaim to release it, and /close once your linked
pull request has merged. Why a command was refused, and how to run the bot as a
GitHub App: docs/issue-commands.md.
Before sending a pull request:
test -z "$(gofmt -l .)"
go vet ./...
go test ./...
go test -race ./...
Keep SSH, protocol and product logic in this repository. A capability that
belongs to the desktop framework should be proposed in Viva instead.
👥 Contributors
📄 License
Motty is released under the Apache License, Version 2.0. See
NOTICE for the copyright and third-party notice. The Motty name and
logo are not licensed under Apache-2.0. Third-party assets and code retain their
own licences.
🙏 Acknowledgements
Motty is built on Viva. Its RDP core is a modified
copy of gopher-rdp, MIT licensed;
the licence and a list of changes are in internal/rdpcore/. Interface icons
come from Lucide, Simple Icons, SVG Logos, Skill Icons, Devicon, selfh.st/icons,
Material Icon Theme and LobeHub Icons; their licences and trademark notes are in
internal/workbench/icons/NOTICE.
