SSH Subsystem Architecture

Overview

The SSH subsystem enables Crab Desktop to manage repositories on remote servers as if they were local. It uses the Remote Agent pattern: the same crab-desktop-agent binary runs on the remote server, and the local Electron app tunnels JSON-RPC 2.0 over an SSH channel.

Key Principle

The renderer is completely unaware of whether a repo is local or remote. All routing happens in the main process via the RPC Router.

Components

Main Process (Electron)

The SSH subsystem runs entirely in the main process with these components:

• SSH Session Manager — connection pool (one TCP conn, many channels), reconnection state machine, suspend/resume detection
• RPC Router — routes repo_id to local agent or remote agent, transparent to renderer
• Response Cache — TTL-based caching with adaptive TTL, invalidation on writes, prefetching
• Agent Deployer — detects remote arch, uploads binary via SFTP, version check + hash-based skip
• Port Forward Manager — local → remote forwards, dynamic detection from terminal output
• File Transfer Manager — SFTP upload/download with progress, transfer queue
• System Health Monitor — polls disk, memory, GPU metrics, alerts on thresholds
• Connection Diagnostics — latency test, bandwidth estimate, recommendations
• Resilience Manager — session persistence, graceful degradation, audit logging
• Performance Manager — prefetching, delta updates, connection pooling, streaming

Remote Server

~/.crab/bin/crab-desktop-agent
  • Same binary, same JSON-RPC protocol
  • Full access to local filesystem + git + crab
  • Spawns CLI tools (crab, git, claude, codex)
  • System health reporting (disk, mem, GPU)

Data Flow

RPC Call (e.g., git status)

1. Renderer calls window.crab.rpc("git_status_porcelain", { repo_id })
2. Main process receives via IPC
3. RPC Router checks repo_id prefix:
   • Local: forward to local agent process
   • Remote (ssh://profileId/path): forward to remote agent channel
4. Remote agent processes request, returns JSON-RPC response
5. Router returns result to renderer via IPC

Connection Lifecycle

The connection progresses through these states:

1. DISCONNECTED → CONNECTING (user initiates connection)
2. CONNECTING → DEPLOYING (SSH handshake succeeds, deploying agent binary)
3. DEPLOYING → CONNECTED (agent binary deployed and started)
4. On network error: CONNECTED → RECONNECTING
5. RECONNECTING → CONNECTED (reconnection succeeds) or DISCONNECTED (60s timeout)

Security Model

• Private keys never leave the local machine
• Credentials stored only in OS keychain
• Host key verification prevents MITM attacks
• Remote agent runs as the user (no privilege escalation)
• Audit log records all connection events (no credentials)
• Port forwards are explicit and user-configured

Error Codes

Performance Targets

Caching Strategy

Adaptive TTL based on connection latency: