Built-in Relay (No VPN Needed)

RemoteConsole includes a built-in relay system that lets your phone connect to your computer from anywhere -- no VPN, no port forwarding, no network configuration. Just install the companion agent on your computer, scan a QR code with your phone, and you are connected.

How It Works

The relay creates a secure bridge between your phone and your computer through a lightweight server:

Phone App  <-->  Relay Server (WebSocket)  <-->  Agent  <-->  Local SSH Server

Your SSH traffic is encrypted end-to-end by the SSH protocol. The relay server only sees opaque binary data -- it cannot read your commands or output.

💡

Tip

The relay is designed for simplicity. If you already use Tailscale or have direct network access to your computer, you can use direct SSH connections instead. Both methods are supported side by side.

Relay vs. Tailscale vs. Direct SSH

Method	Setup	Works Everywhere	Extra Software
Built-in Relay	Scan QR code	Yes	Agent on computer
Tailscale	Install on both devices	Yes	Tailscale on both
Direct SSH	Enter IP address	Same network only	None

Step 1: Install the Agent on Your Computer

The companion agent runs on your computer and bridges relay connections to your local SSH server.

Download a standalone binary -- no Node.js required.

macOS (Apple Silicon)

curl -L -o remoteconsole https://github.com/onurkarali/remoteconsole/releases/latest/download/remoteconsole-macos-arm64
chmod +x remoteconsole
sudo mv remoteconsole /usr/local/bin/

macOS (Intel)

curl -L -o remoteconsole https://github.com/onurkarali/remoteconsole/releases/latest/download/remoteconsole-macos-x64
chmod +x remoteconsole
sudo mv remoteconsole /usr/local/bin/

Linux (x64)

curl -L -o remoteconsole https://github.com/onurkarali/remoteconsole/releases/latest/download/remoteconsole-linux-x64
chmod +x remoteconsole
sudo mv remoteconsole /usr/local/bin/

Windows: download remoteconsole-win-x64.exe from the latest release.

Step 2: Start the Agent

On your first run, provide the relay server URL:

remoteconsole start --relay wss://relay.remoteconsole.app

The agent will:

Check that SSH is available on your computer
Connect to the relay server
Display a QR code for pairing

  RemoteConsole Agent

  SSH server detected on port 22
  Connected to relay server
  Registered with relay server

  Scan this QR code with the RemoteConsole app:

    [QR CODE]

  Or enter code manually: ABCD-EFGH-IJKL

  Agent running. Waiting for connections...
  Press Ctrl+C to stop

ℹ️

Info

The relay URL is saved after the first run. Future starts only need remoteconsole start.

Step 3: Pair Your Phone

Open RemoteConsole on your phone

Tap "Pair via QR Code" on the home screen or tap the + button and select "Pair via QR Code"

Scan the QR code displayed in your terminal. The app will automatically detect your computer's name and configure the connection.

Enter your SSH credentials -- your username and password or SSH key for the remote computer. These are used for SSH authentication and are stored locally on your phone.

Connect -- tap the connection to start a terminal session.

Run as a Background Service

Instead of keeping a terminal open, install the agent as a background service that auto-starts on login:

remoteconsole install

This uses launchd on macOS and systemd on Linux. The agent will start automatically when you log in and restart if it crashes.

To check status or remove the service:

remoteconsole status      # Shows service status (running/stopped)
remoteconsole uninstall   # Stops and removes the service

💡

Tip

Once installed as a service, use remoteconsole pair to display the QR code for pairing new devices.

Agent Commands

Command	Description
`remoteconsole start`	Start the agent in the foreground and show QR code
`remoteconsole install`	Install as a background service (auto-starts on login)
`remoteconsole uninstall`	Stop and remove the background service
`remoteconsole pair`	Show the pairing QR code again
`remoteconsole status`	Show configuration and service status
`remoteconsole reset`	Reset all settings and unpair devices

Options

Flag	Description	Default
`-p, --port <port>`	Local SSH port to bridge	`22`
`--relay <url>`	Relay server URL	Saved from first run

Example with a custom SSH port:

remoteconsole start --port 2222

npm management

# Update to latest version
npm update -g remoteconsole-agent
 
# Uninstall
npm uninstall -g remoteconsole-agent

Prerequisites

Before using the relay, make sure:

SSH is enabled on your computer -- Enable Remote Login guide
Node.js 18+ is installed -- Download Node.js (only needed for npm/npx install; standalone binaries have no dependencies)

Security

End-to-end SSH encryption -- The relay transports opaque binary data. It cannot decrypt your SSH traffic.
Credentials stay on your phone -- SSH username, password, and keys are stored in your phone's secure keychain, never sent to the relay.
Localhost only -- The agent only bridges connections to 127.0.0.1 (your local machine).
Session limits -- Maximum 5 concurrent sessions to prevent resource exhaustion.

⚠️

Warning

The relay server is operated by RemoteConsole. If you prefer not to route traffic through a third-party server, use Tailscale or direct SSH instead.

Troubleshooting

Agent says "No SSH server found"

SSH is not running on your computer. Enable it:

macOS: System Settings > General > Sharing > Remote Login
Linux: sudo systemctl start sshd

See the Enable Remote Login guide for detailed instructions.

Agent cannot connect to relay

Check your internet connection and firewall settings. The agent connects outbound on port 443 (HTTPS/WSS), which is allowed on most networks.

QR code not scanning

Make sure your phone camera can see the entire QR code. Try increasing your terminal font size or moving your phone closer. You can also enter the manual pairing code shown below the QR code.

Connection drops frequently

The agent automatically reconnects with exponential backoff (2s, 4s, 8s, up to 30s). If your connection is unstable, consider installing tmux for persistent sessions that survive disconnects.

Next Steps

Configure SSH keys for password-free login
Install tmux for persistent terminal sessions
Learn about SSH connections in the app