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.
|
Viva talks to Metal, Direct3D and Vulkan directly. Motty starts fast, idles without frame churn, and ships without a browser engine. |
Terminal, SFTP, forwarding, VNC/RDP and the assistant share one workspace. No second app for files, no browser tab for a desktop. |
|
Tabs, splits, SFTP, forwarding and the assistant are commands in the palette. The mouse is optional. |
The repository says what has been verified on real hardware and what has not. The remote-desktop note lists the protocol gaps instead of hiding them. |
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.
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.
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 or Electerm. TOTP/HOTP seeds can be stored in the vault and filled automatically. Saved passwords and key passphrases go into an AES-256-GCM vault; the vault key lives in the system secret store or behind an Argon2id master password.
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.
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.
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, or use its own SOCKS5/HTTP proxy. X11 forwarding validates a per-session fake cookie before replacing it with the local Xauthority cookie.
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. 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.
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.
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.
- 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 |
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. Homebrew, AUR and .AppImage are not available yet.
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.
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/mottyTests 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.txttools/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,debBuild and launch one development binary with:
make runThe binary is built with -tags dev, so its window, in-app title and tray say
Motty Dev. 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.
The development entry shares the default data directory, hosts, settings, AI configuration and vault with the release build. Only the development workspace (the current page, sessions, active session and tab layout) has its own local record, so a development restart does not replace the release workspace. Quit the release build completely, including a copy hidden in the tray, before starting the development build. The builds use the same single-instance claim and do not support parallel writes or live cross-process refresh.
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.
The shared data is not a test sandbox. A development build can upgrade the
configuration or AI schema in a way an older release cannot read, and vault or
cloud-sync operations affect the same daily environment. Back up first and use
an explicit MOTTY_DATA_DIR plus test credentials for migration, deletion,
master-password or secret-reset tests. A separate directory changes application
files only; it does not automatically isolate entries in the system Keychain.
- 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 wrapped by an Argon2id master password.
- 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.
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 |
The QQ group, the WeChat group in its Tencent Doc and the Discord server are all live.
- QQ 群: 1131573299
- 微信群: scan the QR code in the Tencent Doc
- Discord: discord.gg/6s5tn9H4p2
- Bugs and feature requests: GitHub Issues
- Security reports: GitHub private vulnerability reporting
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.
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.
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.