Skip to content

server-management.md

Latest commit

 

History

History
62 lines (35 loc) · 2.25 KB

server-management.md

File metadata and controls

62 lines (35 loc) · 2.25 KB

Server Management

Overview

Relay supports managing connections to multiple remote runners. Servers can be added manually or discovered automatically via mDNS.

Server Types

Local

Direct PTY access on the host machine. Uses SwiftTerm's LocalProcessTerminalView — no runner required. Sessions run the user's default shell.

Remote

Connects to a relay-runner instance via gRPC. Supports both local-mode runners (direct PTY) and cloud-mode runners (Docker-backed sessions).

mDNS Discovery

When mdns.enabled = true in the runner config, the server advertises itself on the local network via Bonjour using the mdns-sd crate.

The Swift client's ServerManagement UI listens for these advertisements and presents discovered servers in the connection dialog.

Configuration:

[mdns]
enabled = true
instance_name = "My Relay Runner"

The instance_name is the human-readable label shown to clients.

Limitation: mDNS requires network_mode: host on Linux Docker. On macOS, use the native (non-Docker) runner for mDNS during development.

Source: runner/src/mdns.rs

Authentication

Servers support two authentication methods that can coexist:

Bearer Token

The client sends Authorization: Bearer <token> with each request. The runner validates against an Argon2 hash stored in config.toml.

Rate limiting is enforced per client IP — exceeding the limit returns HTTP 429 with a Retry-After header.

mTLS

The client presents a certificate issued by the runner's CA. The runner verifies the certificate chain. TOFU (Trust On First Use) verification codes let the user confirm the CA fingerprint.

When require_mtls = true, token-only authentication is rejected.

Source: runner/src/auth.rs, runner/src/tls.rs

Client-Side Architecture

Server management in the Swift client lives in MacApp/Relay/ServerManagement/:

  • ServerListFeature — TCA reducer for the server list, scoped from MainFeature
  • Discovery UI presents mDNS-found servers
  • Connection UI handles auth configuration (token or certificate)
  • GRPCConnectionManager in the RemoteTerminal package handles connection lifecycle with exponential backoff reconnect