Skip to content

client.md

Latest commit

 

History

History
79 lines (58 loc) · 2.6 KB

client.md

File metadata and controls

79 lines (58 loc) · 2.6 KB

Client Setup

Building Relay.app

Requirements

  • macOS 26+ on Apple Silicon (ARM64)
  • Xcode 26.4+
  • SwiftLint: brew install swiftlint

Build from source

# Open in Xcode
open MacApp/Relay.xcodeproj

# Or build from command line
xcodebuild build \
  -project MacApp/Relay.xcodeproj \
  -scheme Relay \
  -destination 'platform=macOS,arch=arm64' \
  CODE_SIGN_IDENTITY=-

Run tests

xcodebuild test \
  -project MacApp/Relay.xcodeproj \
  -scheme Relay \
  -destination 'platform=macOS,arch=arm64' \
  CODE_SIGN_IDENTITY=-

Architecture

The macOS client is built with Swift 6 and The Composable Architecture (TCA). All SPM packages use .swiftLanguageMode(.v6) with strict concurrency.

Packages

Package Purpose
TerminalAbstraction @MainActor protocols: TerminalSession, TerminalEngine, TerminalEvent
TerminalSwiftTerm Local terminal via SwiftTerm's LocalProcessTerminalView
RemoteTerminal gRPC client: bidi streaming, reconnect with backoff, Keychain cert management
TerminalFeature TCA reducer: session lifecycle, remote/local branching
SessionFeature Session management UI and state
AgentOrchestrator Claude Code session management, environment detection
PaneManager Multi-tab terminal management (TabFeature)
WorktreeManager Git worktree sidebar with FSEvents watcher
ProjectFeature Project management UI
SharedModels AppTheme, Project, Session, RemoteProject, RemoteSession value types
CloudClient REST+SSE client for cloud runner communication

App target (MacApp/Relay/)

  • AppFeature — root router
  • MainFeature — coordinator, scopes into AgentOrchestrator, WorktreeManager, TabFeature, ServerListFeature
  • ServerManagement/ — server list, discovery, connection UI

Connecting to a Runner

Local mode

The client can run a local terminal directly via SwiftTerm's LocalProcessTerminalView — no server needed.

Remote mode

  1. Add a server (manually or via mDNS discovery)
  2. If mTLS: import the client certificate issued by relay-runner add-client
  3. If token auth: enter the bearer token
  4. Connect — the client establishes a gRPC channel to the runner

Key patterns

  • TerminalSession protocol — abstracts local PTY (SwiftTermSession) and remote gRPC (RemoteTerminalSession) behind the same interface
  • GRPCConnectionManager — handles reconnection with exponential backoff
  • CertificateManager — stores client certificates in the macOS Keychain
  • AsyncStream — session events flow as TCA Effects