Repository navigation
Connections and Transports
English · Русский
Everything the UI can connect to hides behind one interface in commonMain:
interface SshTransport {
suspend fun connect(target: SshTarget, auth: SshAuth): SshConnection
}SshTarget carries the host, port, user, connectionType, an optional jump chain, the
keep-alive cadence, an optional container spec, and an optional shellCommand that replaces the
login shell on the interactive channel.
RoutingTransport (jvmShared) dispatches on connectionType:
flowchart TD
RT[RoutingTransport] -->|SSH| SSHJ[SshjTransport]
RT -->|MOSH| M[MoshTransport] --> SSHJ
RT -->|CONTAINER| C[ContainerTransport] --> SSHJ
RT -->|TELNET| T[TelnetTransport]
RT -->|SERIAL| SR[SerialTransport]
RT -->|LOCAL| L[LocalShellTransport]
RT -->|VNC / RDP| X[not an SSH transport — VncTransport / RdpTransport]
Mosh and container exec bootstrap over the same injected SSH transport, so host-key trust and ProxyJump behave identically for them. Telnet, serial and local are stateless and default-constructed, and can be swapped in tests.
| Shape | Abstraction |
|---|---|
| "Just a stream" (telnet, serial) | ssh/StreamOnlyConnection |
| Blocking read loop of a shell channel | ssh/StreamShellChannel |
| SSH channel proper | ssh/SshjShellChannel |
| Mosh's own framing | mosh/MoshShellChannel |
Port forwards live in ssh/ForwardState and SshjForwards; the SOCKS5 server behind dynamic
forwarding is ssh/Socks5.kt.
SshJump is one resolved hop with its own auth and its own jump — a linked list resolved
outermost-first, exactly like ssh -J a,b. Host-key verification runs for every hop under its
own (host, port). The UI resolves the chain at connect time and fails the connection on a
dangling id, a non-SSH jump, a secretless jump or a cycle, rather than silently going direct.
trust/HostTrust is the one shape for "ask the user to vouch for a host's identity", used by both
the SSH host key and the RDP certificate:
-
HostTrustPrompt— suspending, implemented by the UI; -
HostTrustDecider— synchronous, what a handshake can call; -
trust/asDecider(jvmShared) bridges the two.
Trust decisions are stored in the vault (VaultKnownHostsStore, VaultTrustedCaStore,
FileRdpCertificateStore). A probe transport is deliberately separate: its verifier does not
add a key to known hosts, so testing a connection never establishes trust.
A connection sometimes has to ask a question mid-handshake — a keyboard-interactive 2FA code, a
host-key decision. Both go through ui/design/PromptQueue, which is a turnstile: two hosts asking
at once queue instead of overwriting each other's dialog, the deadline starts when the question
reaches the screen, and an answer is bound to the question it was given for.
ui/connection/ConnectionController owns connect, reconnect and teardown; ui/session owns tabs,
panes and broadcast. Reconnect applies to types where it is meaningful (carriedBySsh) and is
deliberately not applied to Mosh, which survives outages itself — reconnecting there would open a
second remote session behind the user's back.
From docs/coding-guidelines.md §3, each written after a defect:
- never swallow
CancellationExceptionaround suspend code — cancellation must not masquerade as a network error; - reset guard flags and busy state in
finally, or a cancelled coroutine wedges the feature; - assignment to shared state happens under the same mutex as the check that guarded it (a double connect once leaked a Ktor client);
- a long-lived connection must read incoming frames — a write-only WebSocket handler misses Close and hangs.
User guide
- Installation
- Getting started
- Hosts and connections
- Vault and credentials
- Terminal
- Files (SFTP)
- Port forwarding
- Remote desktops
- Snippets and runbooks
- Monitoring and guard
- AI assistant
- Sync and devices
- Teams and sharing
- Settings and shortcuts
- Android
- Troubleshooting
Development
- Architecture
- Building and running
- Connections and transports
- Terminal engine
- Vault and crypto
- Sync protocol
- Remote desktop stacks
- UI layer
- Testing and the gate
- Contributing and releases
Русский — оглавление