Architecture — In-Process Core, No WebView Bridge

GPUI and the terminal/SSH backend share one Rust process; optional remote agents and platform helpers remain outside this boundary:

┌─────────────────────────────────────────────────┐
│               GPUI Render Loop                  │
│   WorkspaceApp  ·  Tab surfaces  ·  GPUI views  │
└──────────────────────┬──────────────────────────┘
                       │  in-process Arc<> / async
┌──────────────────────▼──────────────────────────┐
│             Domain Crates (Rust async)           │
│  NodeRouter → SshConnectionRegistry             │
│  TerminalState ← SSH PTY channel (russh)        │
│  SftpSession · ForwardingRuntime · IdeWorkspace │
│  Ai/ACP Entities · CloudSync · Plugin Runtimes  │
└─────────────────────────────────────────────────┘

There is no serialization boundary between the UI and the SSH/terminal backend. Terminal bytes mutate TerminalState directly — no JSON, no WebSocket, no Base64, no xterm.js parse pass. GPUI reads the state and emits GPU draw calls.

🔩 Pure Rust SSH — russh (ring)

The desktop app links the russh stack directly:

• No OpenSSL/libssh2 in the SSH stack — SSH cryptography is provided through ring
• Full SSH2: key exchange, channels, SFTP subsystem, port forwarding
• ChaCha20-Poly1305 and AES-GCM, Ed25519/RSA/ECDSA keys
• SSH Agent: Unix (SSH_AUTH_SOCK) and Windows (\\.\pipe\openssh-ssh-agent)
• Custom AgentSigner for russh Signer trait compatibility across .await bounds
• Multi-hop proxy chains with per-hop independent auth

🔄 Smart Reconnect with Grace Period

Reconnect is coordinated by one Rust pipeline:

1. Detect SSH keepalive timeout (Rust async task, no JS timer throttling)
2. Snapshot terminal panes, SFTP transfers, forwards, IDE files — all in-process
3. Grace Period (30 s): probe old SSH connection via keepalive; TUI apps survive on network switch
4. New SSH connection → restore forwards → resume transfers → reopen IDE files

Pipeline: queued → snapshot → grace-period → ssh-connect → await-terminal → restore-forwards → resume-transfers → restore-ide → verify → done

🛡️ SSH Connection Pool

SshConnectionRegistry is backed by DashMap; the workspace uses it through NodeRouter and runtime entities:

• Default shared connection: terminal panes, SFTP, port forwards, and IDE can share one physical SSH connection
• Optional dedicated terminal: a terminal policy can create its own registry key and physical connection without changing the shared node connection
• State machine per connection: connecting → active → idle → link_down → reconnecting
• Node-first addressing: everything is resolved by nodeId → connectionId by NodeRouter
• NodeRuntimeStore: in-process node runtime and serializable topology snapshot; WorkspaceApp helpers persist the snapshot to session_tree.json, while live handles are rebuilt on startup
• Cascade propagation: jump host failure → downstream nodes automatically marked link_down

ConnectionRegistry owns physical connections, health state, consumers, and idle cleanup. WorkspaceRuntimeEntity schedules probes and reconnect jobs. AI and plugins use capability handles, host snapshots, or terminal hooks rather than registering as physical connection consumers.

🤖 OxideSens AI

OxideSens is BYOK-first, with context building performed in-process:

• Providers: OpenAI, Anthropic (Claude), Google Gemini, Ollama/any OpenAI-compatible endpoint
• MCP: stdio + SSE transports, full tool discovery and invocation
• RAG: BM25 full-text + HNSW vector index, Reciprocal Rank Fusion, CJK bigram tokenizer
• Context boundary: provider-bound messages pass through credential-pattern redaction, while the user controls which workspace context and actions are approved
• API keys: stored in the OS keychain and deliberately excluded from structured logs and desktop-core message payloads

🎨 GPUI Desktop Shell

The entire UI is written in Rust using GPUI (Zed's GPU-backed UI framework):

• No CSS, no DOM, no JavaScript in the rendering pipeline
• Workspace tab types: local terminal, SSH, Telnet, Serial, RDP, VNC, SFTP, IDE, port forwards, session manager, cloud sync, settings, plugins, topology, monitoring, file manager, launcher, graphics, and custom plugin tabs
• Split pane system: binary pane tree, draggable dividers, up to 4 panes per terminal tab
• Command palette, global key bindings, sidebar panels — all GPUI primitives
• Immediate-mode rendering: UI reflects Rust state changes without a serialization round-trip

🧱 Terminal State and Rendering

Terminal rendering is modeled as Rust state first, then drawn by GPUI:

• PTY output lands in TerminalState; scrollback, cursor, selection, marks, and search state stay in Rust
• Rendering policy can shift between Boost, Normal, and Idle without asking a browser event loop to cooperate
• Sixel and Kitty graphics are tracked as terminal-owned assets instead of DOM nodes or canvas overlays
• Split panes share the same workspace state model, so tab restore and reconnect can snapshot terminal topology together

🗂️ SFTP and IDE Workspace

Remote files are part of the same node workspace rather than a separate disconnected feature:

• SFTP sessions are resolved through NodeRouter and carry a connection generation; reconnect reacquires an eligible session, but an old-generation operation is never silently replaced by a new connection
• Transfer queues track direction, progress, retry state, and speed limits independently from the visible file panes
• IDE tabs keep dirty buffers, remote paths, conflict state, and restore metadata together
• Remote writes use staged/atomic behavior where the backend supports it, keeping partial writes out of normal edit flows

🧩 Plugins, CLI, and Diagnostics

Extension and support surfaces stay inside explicit Rust-owned boundaries:

• Plugins support manifest-only, WASM, and ordinary process paths. WASM uses Wasmtime/WASI or a sidecar with controlled host calls; process plugins are local processes without an OS sandbox. Legacy Tauri ESM plugins may be shown but are not executed by Native.
• The CLI links directly to domain crates for settings, connections, forwards, plugins, quick commands, secrets, portable bundles, diagnostics, reports, batch plans, backups, and cloud sync
• Diagnostics prefer counts, paths, feature flags, and redacted hints over raw secret-bearing payloads
• Mutating CLI flows use dry-run plans, --yes guards, and rollback backups where applicable

🔀 Port Forwarding — Lock-Free I/O

Forwarding is implemented as a standalone Rust crate:

• Local (-L), Remote (-R), Dynamic SOCKS5 (-D)
• Message-passing architecture: SSH Channel owned by single ssh_io task — no Arc<Mutex<Channel>>
• Auto-restore on reconnect, death reporting, idle timeout

📦 trzsz — In-Band File Transfer

The in-band protocol is integrated directly with native file dialogs:

• Upload/download through the existing terminal stream — no extra ports or agents
• Works through ProxyJump chains
• Native file pickers (no browser memory constraints)
• Bidirectional, directory support, configurable limits

🔐 .oxide Encrypted Export

Portable exports use:

• ChaCha20-Poly1305 AEAD authenticated encryption
• Argon2id KDF: 256 MB memory cost, 4 iterations — GPU brute-force resistant
• Covers: connections, forwards, settings, quick commands, plugin settings, portable secrets