Working SSH, remote workspaces and remote AI preview available

[stephenstack]

@crynta I wanted to share something I have been working on and get your thoughts before considering a pull request.

---

TL;DR

I built a working beta of SSH and remote workspaces for Terax, including remote terminals, SFTP workspaces, SSH config import, jump hosts, port forwarding, host customisation and remote AI execution.
There is a separate Windows preview build available now if anyone wants to install it, kick the tyres and give feedback. It installs alongside the official Terax app and does not replace it.

This is very much a working preview for feedback, not a request to merge a giant PR. I’d especially love feedback from the Terax maintainers and anyone willing to try it with real SSH environments before I break the work into sensible PRs.

Preview: Terax SSH Preview 0.8.6-ssh.2
Source: feat/ssh-remote-sessions

Download Terax SSH Preview 0.8.6-ssh.2

---

First, I genuinely love Terax. The UI, UX and overall terminal-first approach are excellent. I saw that SSH support is the first item under “Coming next” on the roadmap and, honestly, I could not wait to try it.

I have built a working SSH and remote workspace implementation in my fork. Rather than opening a very large unsolicited PR, I created a separate Windows preview so the implementation can be installed, used and discussed first. Theres a ton of stuff below, that i added that I would like to see, and it works really great.

If the direction does not fit what you have planned, that is completely fine too. I still wanted to share a working implementation rather than surprise you with a huge PR. if we can collaborate great, if your already started and going down a different path, no hassle.

High-level features

Remote host management

• Saved SSH host profiles
• Host groups with expandable and collapsible sections
• Drag and drop hosts between groups
• Import hosts and settings from ~/.ssh/config
• Configurable authentication order per host
• Connection status and errors displayed inside the terminal
• Quick actions for terminals, workspaces and tunnels

Remote terminals

• Interactive SSH terminal sessions
• Multiple remote terminal tabs and split panes
• Remote sessions use the existing Terax terminal experience
• Coloured tabs for identifying hosts and environments
• Per-host tab colours
• Per-host terminal backgrounds
• Per-host font, size, weight, cursor and scrollback settings
• Remote working-directory tracking
• Optional file explorer follow mode that follows the active terminal directory
• Clean disconnect and reconnect behaviour
• Remote terminals are deliberately not restored after an application restart

Authentication and host security

• Windows OpenSSH agent support
• PuTTY Pageant support
• Private-key authentication
• Password authentication
• Keyboard-interactive authentication, including OTP-style prompts
• Encrypted private-key passphrase prompts
• Configurable authentication ordering similar to PreferredAuthentications
• OpenSSH known_hosts verification
• Hashed host and non-standard port support
• Unknown-host fingerprint confirmation
• Explicit changed-key and potential MITM warnings
• Accept-once and accept-and-remember options
• Passwords and private-key passphrases are never stored

Remote workspaces

• Open a remote directory as a complete Terax workspace
• Remote file explorer over SFTP
• Browse, open and edit remote files
• Create, rename, move and delete remote files and directories
• Download files from a remote host
• Remote fuzzy file search
• Remote content search and globbing
• Remote Git status and source-control operations
• Remote workspace shown clearly in the status bar
• Switch cleanly between local, WSL and SSH workspaces
• File explorer can follow directory changes in the active remote terminal
• Remote filesystem changes are confined to the authorised workspace root

Jump hosts and forwarding

• ProxyJump support
• Multiple jump-host hops
• Authentication and host-key verification for each hop
• Local port forwarding equivalent to ssh -L
• Configurable local bind address
• Automatic local port selection
• Remote-side hostname resolution
• Clear tunnel status and controls in the Remotes panel
• Forwards close when their remote workspace closes

AI support on remote hosts

• Terax AI shell commands run on the selected remote host
• Commands use the remote workspace directory as their working directory
• Remote execution is kept separate from the local shell path
• Verified protection against accidentally running a remote request on the user’s local machine
• Remote command output is returned through the existing AI tool flow
• Dedicated tests verify remote shell selection and execution routing

Additional UI and terminal work in the branch

• Host and terminal tab colour selection
• Custom hex colours and accent swatches
• Per-host background images
• Improved terminal background transparency
• Sidebar positioning on either side
• Command suggestions based on terminal history
• Improved plain Ctrl+C and Ctrl+V terminal behaviour
• Remote-aware terminal focus and foreground-process handling
• File icon themes with Material and VS Code icon sets
• Persistent Remotes panel section layout

Try the Windows preview

The preview installs separately from the official Terax application and does not replace or update it.

[Download Terax SSH Preview 0.8.6-ssh.2](https://github.com/stephenstack/terax-ai/releases/tag/preview-v0.8.6-ssh.2)

It is currently an unsigned Windows NSIS build, so Windows may display a SmartScreen warning.

Source branch:

[feat/ssh-remote-sessions](https://github.com/stephenstack/terax-ai/tree/feat/ssh-remote-sessions)

Technical and testing guide:

[SSH and remote workspaces documentation](https://github.com/stephenstack/terax-ai/blob/feat/ssh-remote-sessions/docs/ssh-remote.md)

Architecture

I tried to follow the existing Terax architecture and the requirements described in the contribution guide.

• The SSH implementation uses russh, keeping it pure Rust without adding a libssh2 or OpenSSL C dependency.
• Interactive SSH sessions use an interface shaped like the existing PtySession, allowing the terminal frontend to work with local and remote sessions through the same abstraction.
• Interactive terminals and remote workspaces are separate subsystems. SSH owns terminal sessions, while the remote connection pool owns SFTP, command execution and forwarding.
• WorkspaceEnv gains an SSH variant, allowing the existing filesystem, search, Git and AI command boundaries to route work locally or remotely.
• Remote paths remain POSIX strings and are never passed through local Windows PathBuf handling.
• Remote filesystem mutations are confined to the authorised workspace root.
• Search and Git execute on the remote host rather than walking everything through repeated SFTP calls.
• The Remotes frontend is lazy-loaded and connects to the terminal through an opener interface, avoiding a terminal-to-remotes dependency cycle.
• Host-key decisions distinguish trusted, unknown and changed keys. Changed keys are never silently accepted.
• Passwords and private-key passphrases are prompted per connection and are not persisted.
• Session writes, resizing and signals use a single-owner channel rather than sharing the SSH channel behind a lock.
• Remote AI execution uses an explicit remote shell route, with tests ensuring commands cannot fall through to the local host.
• The preview has its own application identifier, registry entries, storage directory and keyring namespace. The official updater is completely disabled.

Lower-level features and fixes

The branch includes a substantial number of edge-case and integration fixes discovered through testing and actual use:

• Separation of SSH session IDs from local PTY IDs
• Correct cancellation of connection prompts when a pane closes
• Protection against sessions being inserted after they were cancelled
• Replacement of stale known_hosts entries after explicit approval
• OpenSSH first-obtained-value-wins configuration parsing
• Support for wildcard and negated SSH config patterns
• Correct authentication ordering and retry behaviour
• Windows SSH agent and Pageant compatibility fixes
• Correct SFTP create, write and truncate flags
• POSIX-compatible search commands for minimal Linux systems
• Safe handling of unusual characters and colons in remote filenames
• Remote path traversal and workspace-boundary protection
• Remote file opening without closing the terminal
• Terminal directory tracking without displaying the injected prompt hook
• Waiting for a settled prompt before installing directory tracking
• File explorer follow mode without taking down the active session
• Remote AI commands executing on the host rather than locally
• Remote sessions excluded from inappropriate local foreground-process checks
• Renderer handling for remote panes and live TUI sessions
• Correct restoration of global appearance after leaving a customised host
• Remote terminals excluded from restart restoration
• Loopback-only port-forward binding by default
• Remote-side resolution of forwarded destinations
• Separate preview registry hooks and file associations
• Stale installer protection in the preview build workflow
• SHA256 generation and exact build provenance for preview releases

The test coverage includes pure unit tests for SSH configuration, targets, host keys, paths, channel selection, keyring isolation, terminal behaviour and remote routing. There is also an optional live integration suite covering SFTP operations, search, Git, jump hosts and port forwarding against a real SSH server.

What I am asking

I am not asking anyone to review or merge the entire branch as one enormous PR.

I would really appreciate your view on:

1. Whether the overall architecture aligns with where you want Terax SSH support to go.

2. Which parts are useful to you.

3. What you would change before any PR is opened.

4. Whether you would prefer this divided into staged PRs, perhaps:

   1. SSH transport, authentication, prompts and known_hosts
   2. Saved hosts, groups and remote terminal UI
   3. SFTP and remote workspaces
   4. File following, remote search and Git
   5. Jump hosts and port forwarding
   6. Remote AI execution
   7. Host colours, backgrounds and appearance
   8. Adjacent terminal improvements as separate contributions

I used Claude Code extensively while implementing this, but I have tested the feature end to end, reviewed the architecture and worked through the Windows, security and isolation edge cases. I am happy to explain the decisions, adjust the implementation and take responsibility for bringing any agreed contribution through review.

If the direction does not fit what you have planned, that is completely fine too. I still wanted to share a working implementation rather than surprise you with a huge PR.