remoteconsole-agent

Companion agent for RemoteConsole — access your computer's terminal from your phone via secure relay.

How it works

The agent runs on your computer and connects to a relay server over WebSocket. When the RemoteConsole app on your phone connects, the agent bridges the session to your local SSH server. All SSH authentication and encryption happens end-to-end between your phone and your computer.

Phone App ←→ Relay (WebSocket) ←→ Agent ←→ Local SSH Server

Requirements

• SSH server enabled on your computer
  • macOS: System Settings > General > Sharing > Remote Login
  • Linux: sudo systemctl start sshd

Install

Standalone binary (no dependencies)

Download from GitHub Releases:

# 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

# Linux (x64)
curl -L -o remoteconsole https://github.com/onurkarali/remoteconsole/releases/latest/download/remoteconsole-linux-x64

npm (requires Node.js 18+)

npm install -g remoteconsole-agent

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

# Uninstall
npm uninstall -g remoteconsole-agent

Quick start

# Start the agent (first run requires --relay)
remoteconsole start --relay wss://relay.remoteconsole.app

# Scan the QR code with the RemoteConsole app on your phone

Run as background service

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

# Install and start the service
remoteconsole install

# Check service status
remoteconsole status

# Stop and remove the service
remoteconsole uninstall

• macOS: Uses launchd (~/Library/LaunchAgents/)
• Linux: Uses systemd user service (~/.config/systemd/user/)

Logs are written to ~/.local/log/remoteconsole-agent.log (macOS) or viewable via journalctl --user -u app.remoteconsole.agent -f (Linux).

Commands

| Command | Description | |---------|-------------| | remoteconsole start | Start the agent and display pairing 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 | | remoteconsole status | Show agent configuration and service status | | remoteconsole reset | Reset all configuration and unpair devices |

Options

| Option | Description | Default | |--------|-------------|---------| | -p, --port <port> | Local SSH port | 22 | | --relay <url> | Relay server URL (wss://) | Required on first run |

Configuration

Configuration is stored at ~/.config/remoteconsole-nodejs/config.json and persists across sessions. The relay URL only needs to be provided once.

Security

• SSH traffic is encrypted end-to-end by the SSH protocol. The relay only sees opaque binary data.
• The relay server bridges WebSocket connections but cannot decrypt SSH traffic.
• The agent only accepts connections to 127.0.0.1 (localhost) by default.
• A maximum of 5 concurrent sessions is enforced to prevent resource exhaustion.
• The agent's device name (your hostname) is shared with paired devices for identification.

License

CC0 1.0 Universal