RemoteConsoleSSHRemoteConsoleSSH|Docs
Home

Relay Connections

Relay connections let you access your computer from anywhere without VPNs or network configuration. This page covers how relay connections work inside the app and how to manage them alongside direct SSH connections.

Adding a Relay Connection

There are two ways to add a relay connection:

QR Code Pairing (Recommended)

  1. Start the companion agent on your computer
  2. In the app, tap + then Pair via QR Code
  3. Scan the QR code displayed in your terminal
  4. Enter your SSH username and password or key
  5. Save the connection

The app automatically fills in the computer name, relay URL, and device ID from the QR code. You only need to provide your SSH credentials.

Manual Code Entry

If the QR code is hard to scan (small terminal, screen glare), the agent also displays a manual pairing code in the format XXXX-XXXX-XXXX. Enter this code in the app's manual pairing screen.

Relay vs. Direct Connections

Both connection types appear in the same connection list. You can tell them apart by the visual indicators:

IndicatorDirect SSHRelay
IconStandard server iconCloud icon
BadgeNone"RELAY" badge
Subtitlehost:portvia relay

Both types support the same features:

  • Full terminal access
  • tmux persistent sessions
  • SFTP file transfer
  • Voice control
  • Keyboard toolbar

How Data Flows

When you connect via relay:

  1. Your phone connects to the relay server over a secure WebSocket (wss://)
  2. The relay routes your connection to the agent running on your computer
  3. The agent opens a local SSH connection on your behalf
  4. SSH performs its own authentication and encryption

The result is two layers of encryption: the WebSocket transport layer (TLS) and the SSH session itself. The relay server handles routing but cannot read the contents of your SSH session.

Managing Relay Connections

Editing a Connection

Tap the connection card, then tap Edit. You can change:

  • Connection name
  • SSH username
  • Authentication method (password or key)
  • SSH port (if your computer uses a non-standard port)

The relay URL and device ID are set during pairing and typically do not change.

Removing a Connection

Swipe left on the connection card and tap Delete. This removes the connection from your phone. The agent on your computer is not affected -- you can re-pair at any time by scanning the QR code again.

Reconnection

If the connection drops (network change, computer sleep, etc.), the app behaves the same as with direct SSH:

  • If tmux is available, your session is preserved on the server
  • The app attempts to reconnect with exponential backoff
  • On reconnect, it reattaches to your tmux session automatically

Mixing Connection Types

You can have both direct SSH and relay connections in the same connection list. This is useful if you:

  • Use relay when away from home (coffee shop, cellular)
  • Use direct SSH when on the same Wi-Fi as your computer (lower latency)
  • Keep Tailscale connections as a backup

All connections are sorted together and can be reordered or organized as you prefer.

Limitations

  • Latency: Relay connections route through an intermediary server, adding some latency compared to direct connections. For most terminal work this is not noticeable.
  • Bandwidth: Large file transfers via SFTP may be slower over relay. For bulk transfers, prefer a direct connection.
  • Agent required: The companion agent must be running on your computer for relay connections to work. If the agent stops, existing connections will close. You can install the agent as a background service so it starts automatically on login.

Next Steps