Connections & Hosts

Architecture

Terminality separates connection intent (what you want to open) from host identity (where you connect). The UI never constructs protocol arguments — Rust generates opaque connection IDs from typed descriptors.

Quick Connections keeps recent destinations and protocol choices close to the tab bar without turning the workspace into a dashboard.

Quick Connection Selector  →  Connection Library  →  Host Catalog
       (ephemeral)              (durable)            (encrypted)

Quick Connection Selector

The + button in the tab bar opens a Rust-backed selector:

• Recent: newest three valid connections.
• More: expandable history beyond three.
• All: full catalog grouped by QuickConnectionKind — a stable registry independent of PaneKind.
• Machine Discovery: runtime-only OrbStack VM listing (macOS). Never imported as Hosts.

The selector is a viewport-level portal: clamps to window, picks flyout side by available space, traps focus, restores focus on dismiss. React Native renders All as a touch accordion in a modal sheet.

Selector invariants:

• Every selector observes the shared Host catalog and connection history — Host changes appear immediately.
• Published choices carry opaque connectionId values, never Host/transport arguments.
• The only direct tab creation command is addLocalTerminalTab (used by ⌘T). All other new-tab and replace-pane workflows go through QCS.

Connection Library

File → Connection Library or ⌘⇧H. A native dialog window, not an in-page modal.

• Search, create, edit, and tombstone-delete Host profiles.
• Per-Host connection eligibility: each Host publishes its available connection kinds — React never reimplements this logic.
• SSH Hosts supply SSH, SFTP, and Omini choices.
• FTP Hosts are independent records — cannot be used as SSH jump hosts.
• RDP Hosts are another independent family with their own endpoint, credentials, and certificate policy.

Host encryption

All Host records are encrypted (XChaCha20-Poly1305) before SQLite persistence. Create/update/delete identity and revision rules stay in Rust. The public binding exposes create, update (revision-checked), and delete — never unrestricted whole-profile save.

Connection Kinds

Kind	Status	Pane Surface
Local Terminal	✓ Complete	localTerminal
tmux Attach	✓ Complete	localTerminal (PTY-less attach)
SSH Terminal	Transport milestone	sshTerminal
SFTP Files	Transport milestone	sftpFiles
FTP Files	Transport milestone	ftpFiles
Omini	Backend-ready	Integrated terminal + files + metrics
RDP	✓ Complete	remoteDesktop (IronRDP)

Machine Discovery

Runtime-only, never persisted. Desktop refreshes on QCS open only.

• macOS: OrbStack adapter — checks Running status first, then bounded JSON listing with hard timeouts. Never starts, stops, or reconfigures VMs.
• Discovered actions remain disabled until the native endpoint resolver and production SSH backend are connected.
• Discovery failures return stable error codes — cannot block existing Host choices.