Connection Proxies

Connection proxies describe how Traversio opens the outer TCP connection before the SSH handshake begins.

Use this feature when the SSH server is reachable through a company proxy such as SOCKS5 or HTTP CONNECT.

Mental Model

your Swift app
    -> external SOCKS5 or HTTP CONNECT proxy
        -> TCP tunnel to the SSH server
            -> SSH handshake starts inside that tunnel

The important part is timing:

• the proxy is used before the SSH identification exchange
• this changes how the TCP connection to the SSH server is created
• this feature applies before any forwarded channel is created

Example: HTTP CONNECT Proxy

import Traversio

let configuration = SSHClientConfiguration(
    host: "ssh.internal.example.com",
    username: "deploy",
    authentication: .password("ssh-password"),
    hostKeyPolicy: .knownHostsFile("/Users/me/.ssh/known_hosts"),
    connectionProxy: .httpConnect(
        SSHHTTPConnectConnectionProxy(
            host: "proxy.corp.example.com",
            port: 8080,
            authentication: .basic(
                username: "corp-user",
                password: "proxy-password"
            )
        )
    )
)

let hostname = try await SSHClient.withConnection(configuration: configuration) { connection in
    try await connection.execute("hostname")
}

Example: SOCKS5 Proxy

import Traversio

let configuration = SSHClientConfiguration(
    host: "ssh.internal.example.com",
    username: "deploy",
    authentication: .password("ssh-password"),
    hostKeyPolicy: .knownHostsFile("/Users/me/.ssh/known_hosts"),
    connectionProxy: .socks5(
        SSHSOCKS5ConnectionProxy(
            host: "proxy.corp.example.com",
            port: 1080,
            authentication: .usernamePassword(
                username: "corp-user",
                password: "proxy-password"
            )
        )
    )
)

Supported Scope

Supported behavior:

• SOCKS5 CONNECT
• SOCKS5 username/password auth
• SOCKS5 no-auth mode
• HTTP CONNECT
• HTTP CONNECT with Basic auth

Limits:

• this applies only to the outermost TCP connection which starts SSH
• there is no SOCKS4 or SOCKS4a support for outer connection proxies yet
• there is no GSSAPI, NTLM, Digest, or other enterprise proxy auth support yet
• the repository now includes a local Docker live-validation matrix for SOCKS5 no-auth, SOCKS5 username/password, HTTP CONNECT no-auth, HTTP CONNECT Basic, and one connectionProxy + proxyJumpHosts path
• broader interoperability coverage remains narrower than the main OpenSSH matrix

How This Relates To ProxyJump

These two features can be combined, and each has a separate responsibility:

• connectionProxy: how Traversio opens the first TCP connection
• proxyJumpHosts: which SSH hop Traversio enters first after that TCP connection exists

So if you configure both:

• Traversio first reaches the first jump host through the external proxy
• later hops travel inside SSH direct-tcpip channels

How This Differs From Dynamic Port Forwarding

This distinction matters:

• connection proxy: Traversio uses an external proxy before SSH starts
• dynamic forwarding: Traversio exposes a SOCKS server for local tools after SSH is connected

If your browser or curl should use a SOCKS endpoint created by Traversio, that is Dynamic Port Forwarding.

If Traversio itself must reach the SSH server through a proxy service, use SSHClientConfiguration.connectionProxy.