Quickstart

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

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

0. Pick A Relay URL

Choose a URL reachable from:

• your phone
• the relay machine
• every agent machine

For same-Wi-Fi testing:

RELAY_URL=http://192.168.1.10:8080

For Tailscale:

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

For public deployment:

RELAY_URL=https://relay.example.com

Avoid localhost unless everything runs on the same machine.

See choosing-relay-url.md.

1. Start The Relay

Clone the repo:

git clone https://github.com/akshaymemane/remote-cli.git
cd remote-cli
cp .env.example .env

Edit .env:

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

Generate a secret:

openssl rand -hex 32

Start:

docker compose up -d

Check logs:

docker compose logs relay

2. Open The PWA

On your phone, open the relay URL:

http://192.168.1.10:8080

Sign in with RELAY_ADMIN_PASSWORD.

3. Install Or Build The Agent

Download the latest binary for your platform from GitHub Releases when one is available:

# macOS Apple Silicon
curl -Lo remote-cli https://github.com/akshaymemane/remote-cli/releases/latest/download/remote-cli-agent-darwin-arm64
chmod +x remote-cli

# Linux arm64, for example Raspberry Pi
curl -Lo remote-cli https://github.com/akshaymemane/remote-cli/releases/latest/download/remote-cli-agent-linux-arm64
chmod +x remote-cli

Or build from source:

go build -o remote-cli ./cmd/agent
chmod +x remote-cli

Optionally place it on your PATH:

mkdir -p ~/.local/bin
mv remote-cli ~/.local/bin/

Confirm:

remote-cli status

If the shell cannot find remote-cli, use ./remote-cli from the build directory or add ~/.local/bin to your PATH.

4. Confirm Claude Works Locally

On the agent machine:

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 the agent machine:

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.

6. Run The Agent

Pairing saves credentials. It does not keep the agent online.

Run:

remote-cli run

Keep this process running.

The PWA should show the device online.

To keep the agent online in the background on macOS or Linux:

remote-cli service install
remote-cli service logs

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:

remote-cli pair --relay http://192.168.1.10:8080
remote-cli run

Each machine appears as a separate device in the PWA.

Next Steps

• Relay Deployment
• Agent Install
• Service And Autostart
• Troubleshooting