SSH & Remote Connections
Relevant source files
The following files were used as context for generating this wiki page:
SSH & Remote Connections provide the infrastructure for Termul Manager to interact with remote servers. This system enables users to manage remote terminal sessions and perform file operations through an integrated SFTP interface. The application treats remote connections as a distinct domain within the workspace, allowing for project-specific remote access.
The module integrates with the OS keychain to secure credentials and uses the ssh2 library for protocol handling. It supports persistent host-key verification and local port forwarding via the active session.
Architecture and Data Flow
The SSH implementation follows a multi-layered architecture involving the React frontend, Zustand state management, and the Rust-based Tauri backend. Remote operations are abstracted through an API layer that branches between Tauri-native calls and web-based transports.
The diagram shows the flow from the user interface components to the remote server, including the credential retrieval from the OS keychain.
Sources: src/renderer/layouts/WorkspaceLayout.tsx:143, README.md:230-245
Profile and Connection Management
Termul manages remote connections using profiles stored in ssh-profiles.json. Each profile contains connection metadata such as host, port, and username. Sensitivie data, including passwords and key passphrases, are excluded from this file and stored in the OS keychain.
Connection Lifecycle
- Authentication: Users select a profile. If no password exists in the keychain, the UI prompts for input.
- Establishment: The system initiates the connection via the Tauri backend.
- Status Tracking: The application tracks connection health (connected, reconnecting, failed) through a dedicated status store.
- Disconnection: Users can manually terminate sessions, which cleans up active port forwards and PTY sessions.
This sequence illustrates the authentication and connection flow when a user selects a remote profile.
Sources: src/renderer/layouts/WorkspaceLayout.tsx:550-600, README.md:230-235, src/renderer/components/ssh/SSHPanel.test.tsx:160-175
SFTP and Remote File Systems
The remote connection system includes full SFTP support for file management. This allows users to browse remote directories and perform standard filesystem operations through the SSHFileExplorer component.
Supported SFTP Operations
| Operation | Function | Description |
|---|---|---|
| Mkdir | sftpMkdir | Creates a new directory on the remote host. |
| Create File | sftpCreateFile | Generates a new empty file at the specified remote path. |
| Delete | sftpDelete | Removes files or directories from the remote server. |
| Rename | sftpRename | Modifies the name or path of a remote entry. |
| Browse | loadDirectory | Lists the contents of a remote directory. |
Sources: src/renderer/layouts/WorkspaceLayout.tsx:440-520, CHANGELOG.md:58-60
Security and Port Forwarding
The SSH module enforces secure practices by default. It utilizes OpenSSH's default known-hosts file and sets StrictHostKeyChecking to accept-new to ensure host-key verification is not bypassed.
Local Port Forwarding
Termul supports local port forwarding using ssh2 channel_direct_tcpip. This allows traffic from a local port to be tunneled through the active SSH session to a target host and port accessible by the remote server. Remote (reverse) forwarding is currently not supported.
The diagram represents the data path for local port forwarding through an established SSH tunnel.
Sources: README.md:235-242, src/renderer/lib/tests/parity-checklist.test.ts:180-195
Parity and Platform Support
The SSH feature maintains parity across different platforms, though implementation details vary by target OS. On macOS, the system uses vendored OpenSSL to avoid dependencies on external library paths like Homebrew. Windows and Linux versions utilize the system's default OpenSSL behavior.
Parity Checklist
- Keychain Persistence: Credentials remain secure across app restarts.
- Host-Key Verification: Host identity is verified against
known_hosts. - Terminal Integration: Remote shells integrate into the standard workspace pane layout.
Sources: README.md:240-248, src/renderer/lib/tests/parity-checklist.test.ts:1-20
Conclusion
SSH & Remote Connections in Termul provide a secure and integrated way to manage remote environments. By combining terminal access with SFTP file management and secure credential storage, the system ensures that remote projects are as accessible and manageable as local ones.