Overview

Traversio is a native Swift SSH and SFTP client library for Apple platforms. It provides async/await connection ownership, host-key trust, command execution, PTY shells, file transfer, forwarding, SCP helpers, and structured diagnostics on a testable protocol stack.

Start here when evaluating the package or wiring it into an Apple app.

Start with Why Traversio for the design rationale. Start with Mental Model for the public object model and the main workflows.

Supported In This Release

• The current public platform floor is documented in Quickstart and declared directly in Package.swift.
• SSHClient.connect(configuration:) provides explicit long-lived connection ownership.
• SSHClient.withConnection(configuration:_:) provides the same connection path in a closure-scoped form.
• SSHClientConfiguration supports RFC 4253 zlib, delayed OpenSSH [email protected], automatic rekey policy, idle keepalive, a default 30-second setup timeout, and explicit reply timeouts.
• SSHClient.connect(...) and SSHClient.withConnection(...) support logHandler: for structured lifecycle and failure events.
• Password authentication, keyboard-interactive authentication, Ed25519, RSA, and ECDSA public-key authentication, callback-backed signing, and SSH agent-backed signing are available.
• OpenSSH-compatible key generation is available through SSHOpenSSHKeyPair.generate(...).
• The public connection API covers remote commands, PTY-backed shells, SFTP, single-file SCP helpers, raw direct-tcpip, [email protected], forwarded-tcpip, and [email protected] channels, local and dynamic forwarding helpers, raw remote TCP and streamlocal listeners, and a remote-forward bridge helper.
• SSHClientConfiguration supports SOCKS5 and HTTP CONNECT outer connection proxies plus multi-hop proxyJumpHosts.
• The SFTP surface covers version exchange, metadata queries, attribute updates, filesystem queries, directory listing, public file handles, bounded concurrent whole-file reads, bounded concurrent whole-file writes, optional OpenSSH fsync, rename, remove, directory creation or removal, symlink creation, and readlink.
• Host trust supports exact key pinning, trusted key sets, first-seen and changed-key helpers with app-owned persistence, async trust callbacks, and OpenSSH known_hosts.
• Current validation covers OpenSSH, Dropbear, AsyncSSH, proxy routing, ProxyJump, rekey, compression, adverse connection paths, and repeated long-running workloads.

Known Limits

• Traversio does not own automatic reconnect, session restoration, credential storage, or mandatory trust-store persistence. Applications should build those policies above SSHConnection.
• Host-certificate coverage is focused on Ed25519 and ECDSA P-256 paths.
• Forwarding covers the documented raw, local, dynamic, remote, streamlocal, proxy, and ProxyJump paths. Broader server-family and enterprise-proxy coverage remains future compatibility work.
• Cancellation and peer-shutdown behavior is explicit but still conservative: when cancellation wins, operations generally throw CancellationError; when transport loss or protocol failure wins, callers should handle the typed Traversio failure.

Status

Traversio 1.0.x documents the current supported workflows for Apple apps that need native Swift SSH, SFTP, and forwarding. It does not mean every server, proxy, network, and long-running deployment shape has already been covered.

Recommended Reading Order

Recommended reading order for the fastest path from "what is this?" to "how do I use it?":

1. Mental Model
2. Quickstart
3. Diagnostics
4. Running Commands or Interactive Shell
5. SFTP or Forwarding
6. Public API
7. Architecture

Library Areas

Use the section cards below to jump straight to the topic you need. Larger subjects such as authentication, session workflows, and SFTP are grouped into dedicated sections.