Skip to content
Lobster

Remote Access

Remote Access with Tailscale

Secure remote access to your OpenClaw agent using Tailscale — an encrypted mesh VPN that works through NAT and firewalls without exposing ports to the internet.

Why Tailscale?

Traditional SSH exposes port 22 to the internet and requires port forwarding. Tailscale provides:

  • Encrypted end-to-end — All traffic encrypted between devices
  • No port forwarding — Works through NAT and firewalls automatically
  • Access controls — Fine-grained ACLs per device and user
  • SSH integration — Tailscale SSH replaces macOS sshd entirely
  • MagicDNS — Access devices by name (e.g., ssh your-agent)

Installation

Important: Use the Homebrew CLI installation, not the GUI app.

Terminal window
brew install tailscale
brew services start tailscale

Why not the GUI app? Both the Mac App Store and standalone .pkg versions are sandboxed — they can’t host SSH or properly configure DNS. Only the Homebrew formula provides unsandboxed tailscaled.

Authenticate and enable SSH:

Terminal window
sudo tailscale up --ssh

SSH Configuration

Disable macOS sshd

Once Tailscale SSH is working, disable the built-in SSH server:

Terminal window
sudo systemsetup -setremotelogin off

Add SSH Config Entry

On your client machine, add to ~/.ssh/config:

Host your-agent
    HostName your-agent.your-tailnet.ts.net
    User AGENT_USER
    IdentityFile ~/.ssh/id_ed25519

Now you can simply run:

Terminal window
ssh your-agent

PATH for Non-Interactive SSH

Non-interactive SSH sessions have a minimal PATH. Prefix commands with the full PATH:

Terminal window
ssh your-agent "export PATH=/opt/homebrew/bin:/opt/homebrew/sbin:\$PATH; openclaw status"

Tailscale Serve (Dashboard Access)

Expose the OpenClaw dashboard to your tailnet without opening ports:

Terminal window
sudo tailscale serve --bg 18789

This maps https://your-agent.your-tailnet.ts.net to 127.0.0.1:18789 over the tailnet only. The gateway stays bound to loopback for security.

Access the dashboard from any device on your tailnet:

https://your-agent.your-tailnet.ts.net/?token=YOUR_GATEWAY_TOKEN

Find your token:

Terminal window
openclaw config get gateway.auth.token

ACL Configuration

Configure Tailscale ACLs so the agent machine cannot initiate connections to other devices:

{
  "tagOwners": {
    "tag:agent": ["autogroup:admin"]
  },
  "grants": [
    // Personal devices talk freely
    { "src": ["autogroup:member"], "dst": ["autogroup:member"], "ip": ["*"] },
    // Personal devices can reach agent
    { "src": ["autogroup:member"], "dst": ["tag:agent"], "ip": ["*"] }
    // IMPORTANT: No grant allows tag:agent as src.
  ],
  "ssh": [
    // Personal devices — auto-accept
    { "action": "accept", "src": ["autogroup:member"], "dst": ["autogroup:self"], "users": ["autogroup:nonroot", "root"] },
    // Agent — require browser re-authentication
    { "action": "check", "src": ["autogroup:member"], "dst": ["tag:agent"], "users": ["AGENT_USER", "root"] }
  ]
}

Tag the agent machine as tag:agent in your Tailscale admin console.

Verify Network Isolation

Terminal window
# From agent Mac (should FAIL/timeout):
tailscale ping your-main-mac


# From your main Mac (should SUCCEED):
tailscale ping your-agent

Tailscale Lock

Enable Tailscale Lock with your phone and laptop as trusted approval devices. This prevents unauthorized devices from joining your tailnet.

Common Remote Commands

Terminal window
# Check agent status
ssh your-agent "export PATH=/opt/homebrew/bin:\$PATH; openclaw status"


# View recent logs
ssh your-agent "export PATH=/opt/homebrew/bin:\$PATH; openclaw logs --tail 50"


# Restart gateway
ssh your-agent "export PATH=/opt/homebrew/bin:\$PATH; openclaw gateway restart"


# Run diagnostics
ssh your-agent "export PATH=/opt/homebrew/bin:\$PATH; openclaw doctor --deep"

Node Access (Multi-Mac Setup)

Connect another Mac as a node pointing to the agent’s gateway:

Terminal window
# On your other Mac
npm install -g openclaw
openclaw node install --host your-agent.your-tailnet.ts.net --port 443 --tls


# On the agent Mac, approve the pairing
openclaw nodes pending
openclaw nodes approve <requestId>


# Now use the TUI and dashboard from your other Mac
openclaw tui
openclaw dashboard

Troubleshooting

Tailscale DNS / Serve Not Working

Use the Homebrew CLI (brew install tailscale), not the GUI app.

Stale Tailscale Shim

If you previously installed the Mac App Store version, a shim script at /usr/local/bin/tailscale may shadow the real binary:

Terminal window
sudo rm /usr/local/bin/tailscale

SSH Hangs or Timeouts

Check that Tailscale SSH is enabled:

Terminal window
tailscale status

If SSH is not shown, re-enable:

Terminal window
sudo tailscale up --ssh