RelayBar: A Lightweight macOS Menu-Bar Utility for SSH Tunneling

RelayBar is a streamlined, native macOS application residing in the menu bar, specifically designed to manage local SSH port forwards without the overhead of complex configurations.

🚀 Core Functionality

RelayBar acts as a wrapper for the system's native SSH client. It does not rely on third-party libraries, instead executing /usr/bin/ssh directly.

Key Capabilities

• Command Integration: Easily import standard strings such as ssh -N -L 8080:localhost:3000 user@host.
• Manual Configuration: Create tunnels via a simple interface consisting of five input fields.
• One-Click Control:
  • Toggle tunnels on or off instantly.
  • Launch a tunnel and automatically open the associated local URL in your default web browser.
• Resilience: If a connection drops unexpectedly, the app employs an exponential backoff strategy to retry the connection up to 10 times. The retry delay can be conceptualized as: $\text{delay} = \text{base} \times 2^n$
• Visibility: Startup errors are displayed immediately adjacent to the affected tunnel.
• Lifecycle Management:
  • Tunnel settings are persisted using local UserDefaults.
  • All child SSH processes are terminated automatically when the application quits.

Note: RelayBar is designed to handle exactly one local (-L) forward per entry.

Workflow Visualization

🛡️ Security & Architecture

RelayBar is distributed via the Mac App Store distributed independently and is intentionally not sandboxed. This allows it to function similarly to a terminal-based SSH client.

Permission & Access

• SSH Environment: It inherits the user's ~/.ssh/config and known_hosts, utilizes configured identity files, and integrates with the user's SSH agent.
• Network Access: On modern macOS versions, users may be prompted to grant "Local Network" access when connecting to LAN or .local hosts.
• Interaction: Because SSH runs in a non-interactive mode, password prompts are not supported.

Command Filtering

To ensure safety, RelayBar filters the flags allowed during command imports:

🛠️ Development & Build Process

System Requirements

• OS: macOS 13 or higher.
• Tools: Xcode command-line tools.

Build Pipeline

To compile and package the application, follow these steps:

• Build the App:

  ./scripts/build-app.sh
  # The output is located at .build/RelayBar.app
  

• Create Release Archive:

  ./scripts/package-release.sh
  # This generates .build/RelayBar.zip
  

• Notarization: To bypass Gatekeeper warnings, the app must be notarized. First, store your credentials: xcrun notarytool store-credentials relaybar-notary --apple-id YOUR_APPLE_ID --team-id YOUR_TEAM_ID --password YOUR_APP_SPECIFIC_PASSWORD

  Then, run the notarization script:

  NOTARY_PROFILE=relaybar-notary ./scripts/notarize-release.sh
  

  (Optional: Use SIGNING_IDENTITY if multiple Developer ID certificates exist on the machine.)

Testing

Run the test suite using: swift test

📊 Project Metadata