Relay Deployment

The relay is the central server. Phones and agents connect to it over HTTP/WebSocket.

The recommended beta path is the local remote-cli binary installed through npm. Docker remains available for advanced deployments.

Responsibilities

The relay:

• serves the embedded PWA
• authenticates phone sessions
• handles pairing
• stores device/admin state in SQLite
• tracks active WebSocket connections
• routes session messages between phones and agents

Local Binary

Install:

npm install -g @akshaymemane/remote-cli

Create relay config:

remote-cli relay init

Start:

remote-cli relay start

Open:

remote-cli relay open

Check:

remote-cli relay status
remote-cli doctor

The relay config is stored at:

~/.config/remote-cli/relay.toml

The default database path is:

~/.config/remote-cli/relay.db

Non-Interactive Init

For scripts:

remote-cli relay init \
  --url http://192.168.1.10:8080 \
  --addr :8080 \
  --admin-password "change-this-password"

Then start:

remote-cli relay start

Environment Variables

Environment variables override config at runtime:

Variable	Purpose
RELAY_ADDR	Listen address. Default: :8080.
RELAY_DB	SQLite database path.
RELAY_JWT_SECRET	Secret for signing phone JWTs.
RELAY_URL	Public/reachable base URL used for pairing and PWA access.
RELAY_STATIC_DIR	Directory for built PWA assets. Useful for development.
RELAY_ADMIN_PASSWORD	Optional non-interactive first-run admin password.

SQLite Data

The relay stores:

• admin password hash
• device IDs
• device token hashes
• device names
• last-seen timestamps

Back up relay.db if you care about preserving paired devices.

TLS

Use TLS for public deployments.

Caddy example:

relay.example.com {
    reverse_proxy localhost:8080
}

nginx example:

location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Deployment Options

LAN

Good for first tests.

remote-cli relay init --url http://192.168.1.10:8080

Tailscale

Good for private remote access.

remote-cli relay init --url http://relay-host.tailnet-name.ts.net:8080

Public VPS

Good for always-on access.

remote-cli relay init --url https://relay.example.com

Docker Compose

Docker is an advanced path, not required for the first beta install.

Create .env from the example:

cp .env.example .env

Set:

RELAY_URL=http://192.168.1.10:8080
RELAY_JWT_SECRET=<generate-with-openssl-rand-hex-32>
RELAY_ADMIN_PASSWORD=<choose-a-password>

Start:

docker compose up -d

Check:

docker compose ps
docker compose logs relay

Running From Source

For development, build the PWA and serve it from disk:

cd pwa
npm install
npm run build
cd ..
go run ./cmd/remote-cli relay start --static-dir pwa/dist

Admin Password Reset

remote-cli relay reset-password

Production Notes

Before public exposure:

• use HTTPS
• set a strong relay admin password
• protect the SQLite database
• avoid running on a laptop that sleeps
• prefer Tailscale or a private network while the project is still early