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
Node.js 20+ (download)

Install

npm install -g remoteconsole-agent

# Uninstall (run `remoteconsole uninstall` first if you installed the service)
npm uninstall -g remoteconsole-agent

Update

npm install -g remoteconsole-agent@latest
remoteconsole restart   # only if you run it as a background service

A running agent keeps its old code until it restarts. remoteconsole restart also re-points the service at the newly installed copy, which matters if you updated under a different Node version (e.g. after switching with nvm). Your device ID and pairings live in the config file and survive updates.

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 restart`	Restart the background service (after an update)
`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 ~/Library/Preferences/remoteconsole-nodejs/config.json (macOS) or ~/.config/remoteconsole-nodejs/config.json (Linux) and persists across sessions and updates. remoteconsole status prints the exact path. 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.