Agent Install

Install remote-cli on every machine you want to control.

The agent:

• pairs with the relay
• stores a device credential locally
• keeps an outbound WebSocket connection to the relay
• starts Claude Code when the PWA opens a session

Requirements

Each agent machine needs:

• macOS or Linux
• Node.js 18+ and npm for the recommended install path
• Claude Code installed
• Claude Code authenticated
• network access to the relay URL

Verify Claude:

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

Recommended Install

npm install -g @akshaymemane/remote-cli

The npm package has no runtime dependencies. It installs a small launcher and downloads the matching GitHub Release binary into the package cache.

Supported beta assets:

remote-cli-darwin-arm64
remote-cli-darwin-amd64
remote-cli-linux-arm64
remote-cli-linux-amd64
checksums.txt

Confirm:

remote-cli version
remote-cli --help

Manual Binary Install

Download the latest binary for your OS/architecture from GitHub Releases:

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

# macOS Intel
curl -Lo remote-cli https://github.com/akshaymemane/remote-cli/releases/latest/download/remote-cli-darwin-amd64
chmod +x remote-cli

# Linux amd64
curl -Lo remote-cli https://github.com/akshaymemane/remote-cli/releases/latest/download/remote-cli-linux-amd64
chmod +x remote-cli

# Linux arm64
curl -Lo remote-cli https://github.com/akshaymemane/remote-cli/releases/latest/download/remote-cli-linux-arm64
chmod +x remote-cli

Install it somewhere on your PATH:

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

Build From Source

Requires Go 1.23+:

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

Pair And Run

remote-cli pair --relay http://YOUR_RELAY_URL

The command prints:

• QR code
• 6-digit code
• pairing URL

Use the PWA to scan or enter the code.

Config is written to:

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

remote-cli pair starts the agent after pairing. Keep it running while manually testing.

Run Later

After pairing:

remote-cli run

The PWA should show the device online.

Check Status

remote-cli status

This shows whether the machine is paired and which relay URL is stored.

Unpair

remote-cli unpair

This removes the local agent config. It does not delete the relay-side device record. Delete the device from the PWA if you also want to remove it from the relay.

Autostart

On macOS and Linux, install the agent as a background service:

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

See service-autostart.md.