Tailscale Setup

Tailscale is the easiest way to run remote-cli across multiple machines and your phone. One install per device, one-time auth — all your devices share a private network automatically. No port forwarding, no dynamic DNS, no firewall rules.

Why Tailscale Works So Well Here

remote-cli needs three things to reach each other over a stable, private URL:

• relay host
• agent machines (laptops, desktops, servers)
• your phone

Tailscale solves all three with a single mesh VPN. Every device gets a stable IP (100.x.y.z) and an optional DNS name (machine.tailnet-name.ts.net) that never changes, even if you switch networks or reboot.

After the one-time setup below, adding a new machine is just: install Tailscale, run tailscale up.

What You Need

• A free Tailscale account (supports up to 100 devices)
• Tailscale installed on:
  • the machine running the relay
  • every machine running an agent
  • your phone (iOS or Android)
• remote-cli installed on the relay and agent machines

Step 1 — Install Tailscale Everywhere

macOS / Linux (relay + agent machines):

# macOS
brew install tailscale

# Linux (Debian/Ubuntu)
curl -fsSL https://tailscale.com/install.sh | sh

Then authenticate:

tailscale up

This opens a browser to log in with your Tailscale account. Do this on every machine.

Phone:

Install the Tailscale app from the App Store or Google Play, then sign in with the same account.

Step 2 — Enable MagicDNS (Recommended)

MagicDNS gives every device a stable hostname like my-macbook.tailnet-name.ts.net instead of a raw IP.

Enable it once in the Tailscale admin panel:

1. Go to login.tailscale.com/admin/dns
2. Toggle MagicDNS on

Now you can use hostnames instead of IPs everywhere in remote-cli config.

Step 3 — Find Your Relay Machine's Tailscale Address

On the relay machine:

tailscale status

Look for your machine's entry. The IP starts with 100.. The MagicDNS name is shown as <hostname>.<tailnet-name>.ts.net.

Example output:

100.64.0.1   my-macbook   user@  macOS   -

With MagicDNS enabled, you can use either:

• http://100.64.0.1:8080
• http://my-macbook.tailnet-name.ts.net:8080

Step 4 — Initialize The Relay With The Tailscale URL

On the relay machine, run setup with the Tailscale address:

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

Or with the raw IP:

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

Start the relay:

remote-cli relay start

The relay now listens on :8080. Because it binds to all interfaces, Tailscale traffic reaches it on the 100.x.y.z interface automatically — no extra config needed.

Step 5 — Pair Each Agent Machine

On each machine you want to control remotely:

remote-cli pair --relay http://my-macbook.tailnet-name.ts.net:8080

This prints a QR code and pairing URL. Scan it from the PWA on your phone.

If the relay is on the same machine as the agent, you can use localhost:

remote-cli pair --relay http://localhost:8080

Step 6 — Open The PWA On Your Phone

Open the Tailscale app on your phone and make sure it is connected.

Then open your phone browser and navigate to:

http://my-macbook.tailnet-name.ts.net:8080

Log in with the relay admin password. Your paired devices will appear.

Step 7 — Install Agents As Services (Optional)

So agents survive reboots without manual restarts:

remote-cli service install
remote-cli service start

Run this on each agent machine. The service auto-reconnects to the relay after network changes, including Tailscale reconnects.

Summary: What You Set Once

Thing	Set once?
Tailscale account	Yes
Tailscale on relay machine	Yes
remote-cli relay init with Tailscale URL	Yes
Tailscale on phone	Yes
MagicDNS enabled	Yes

After this, adding a new agent machine is just:

# On the new machine
tailscale up
remote-cli pair --relay http://my-macbook.tailnet-name.ts.net:8080
remote-cli service install && remote-cli service start

Verification Checklist

Before pairing, verify connectivity from each machine:

# From agent machine — should return relay HTML or JSON
curl http://my-macbook.tailnet-name.ts.net:8080

# From the relay machine — verify Tailscale is up
tailscale ping <agent-machine-hostname>

From your phone browser, open the relay URL. If the remote-cli login page loads, networking is correct.

Troubleshooting

Relay URL unreachable from phone

• Check Tailscale is connected on phone (green icon in app)
• Check relay machine is also connected: tailscale status
• Ensure relay is running: remote-cli relay status

Agent shows offline after network change

Tailscale reconnects automatically. The agent service reconnects when the relay is reachable again. Check with:

remote-cli service status
remote-cli service logs

MagicDNS names not resolving

On Linux, some DNS configs require enabling Tailscale's DNS:

tailscale up --accept-dns

Port 8080 already in use

Change the relay port:

remote-cli relay init --url http://my-macbook.tailnet-name.ts.net:9090
RELAY_ADDR=:9090 remote-cli relay start

Then pair agents with the new port.

Security Notes

• Traffic stays inside your Tailscale network. The relay is not exposed to the public internet.
• Tailscale uses WireGuard under the hood — end-to-end encrypted between devices.
• The relay still issues its own JWT for phone authentication. Even if someone joined your tailnet, they would need the relay admin password to control sessions.
• For extra isolation, use Tailscale ACLs to restrict which tailnet devices can reach the relay port.