remote-cli

Appearance

Quickstart ​

This guide gets one relay, one phone/PWA, and one agent machine working from a fresh machine.

For multi-device setups, repeat the install and pairing steps on every machine that should run the agent.

0. Pick A Relay URL ​

Choose a URL reachable from:

  • your phone
  • the relay machine
  • every agent machine

For same-Wi-Fi testing:

bash
http://192.168.1.10:8080

For Tailscale:

bash
http://relay-host.tailnet-name.ts.net:8080

For public deployment:

bash
https://relay.example.com

Avoid localhost unless the phone, relay, and agent all run on the same machine.

See choosing-relay-url.md.

1. Install remote-cli ​

Install the CLI:

bash
npm install -g @akshaymemane/remote-cli

Confirm:

bash
remote-cli version
remote-cli --help

The npm package downloads the matching GitHub Release binary for macOS or Linux.

2. Run Setup ​

On the machine that should host the relay:

bash
remote-cli setup

For a first test, choose both if you want the relay and an agent on the same machine.

Setup asks for:

  • what this machine should run: relay, agent, or both
  • relay URL
  • relay admin password
  • whether to start the relay now
  • whether to pair and start the agent now

It writes config under:

text
~/.config/remote-cli/

3. Open The PWA ​

If setup did not start the relay, start it:

bash
remote-cli relay start

Open the relay URL on your phone:

text
http://192.168.1.10:8080

Sign in with the admin password you chose during setup. The PWA is served by the relay from assets embedded in the remote-cli binary.

4. Confirm Claude Works Locally ​

On every agent machine:

bash
which claude
claude --version
claude --print "Reply with OK"

If Claude Code is not installed, not authenticated, or rate-limited, remote-cli will not be able to get a useful response from that machine.

5. Pair The Agent ​

On each machine you want to control:

bash
npm install -g @akshaymemane/remote-cli
remote-cli pair --relay http://192.168.1.10:8080

The terminal prints a QR code and a 6-digit code.

In the PWA:

  1. Tap add device.
  2. Scan the QR code or enter the code manually.
  3. Wait for the terminal to say pairing succeeded.

remote-cli pair starts the agent after pairing. Keep that process running while testing.

6. Install The Agent Service ​

For day-to-day use, run the agent as a background service:

bash
remote-cli service install
remote-cli service status
remote-cli service logs

The service keeps the device online after terminal windows close and across restarts on supported systems.

7. Start A Session ​

In the PWA:

  1. Tap the online device.
  2. Wait for the session to start.
  3. Send a prompt.

Claude runs on the selected agent machine, not on the relay.

8. Add More Machines ​

Repeat on each laptop, desktop, or Raspberry Pi:

bash
npm install -g @akshaymemane/remote-cli
remote-cli pair --relay http://192.168.1.10:8080
remote-cli service install

Each machine appears as a separate device in the PWA.

Useful Checks ​

bash
remote-cli doctor
remote-cli relay status
remote-cli status
remote-cli service status

Next Steps ​

Released under the MIT License.

Copyright © 2026 remote-cli contributors