48Nauts-Operator/clawdbot-tailscale.md

## clawdbot-tailscale.md

      
    Raw
  

              clawdbot-tailscale.md
            
          
    Clawdbot + Tailscale Remote Access: Complete Setup Guide

Last Updated: January 2026
Clawdbot Version: 2026.1.24-3+
Applies To: Self-hosted Clawdbot with remote access needs

Overview

Setting up secure remote access for your self-hosted Clawdbot using Tailscale Serve. This guide covers the configuration conflicts, security model, and troubleshooting steps that aren't fully documented in the beta docs yet.
What you'll get:

✅ Access your Clawdbot from anywhere on your Tailscale network
✅ Two-layer security (Tailscale auth + Clawdbot device pairing)
✅ No port forwarding or public exposure needed
✅ HTTPS encryption via Tailscale


Prerequisites


Tailscale account and client installed
Clawdbot installed and working locally
Basic familiarity with JSON configuration files


The Problem & Solution

Issue: Gateway Binding Conflicts

Symptom:
Gateway failed to start: Error: tailscale serve/funnel requires gateway bind=loopback (127.0.0.1)

Root Cause:
You can't use gateway.bind: "lan" (listens on all interfaces) with tailscale.mode: "serve". Tailscale Serve requires the service to be bound to loopback for security.
Issue: "Pairing Required" After Tailscale Setup

Symptom:
WebSocket disconnected (1008): pairing required

Root Cause:
Clawdbot uses a two-layer security model. Even with Tailscale authentication, each device needs explicit approval via Clawdbot's device pairing system.

Configuration Steps

Step 1: Update Gateway Configuration

Edit your ~/.clawdbot/clawdbot.json:
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "trustedProxies": ["127.0.0.1", "::1", "100.0.0.0/8", "fd7a:115c:a1e0::/48"],
    "tailscale": {
      "mode": "serve",
      "resetOnExit": false
    }
  }
}
Key Changes Explained:

bind: "loopback" - Gateway only listens on 127.0.0.1 (required for Tailscale Serve)
trustedProxies - Allows Tailscale to forward client IP addresses properly

127.0.0.1, ::1 - Local loopback addresses
100.0.0.0/8 - Tailscale IPv4 CGNAT range
fd7a:115c:a1e0::/48 - Replace with your Tailscale IPv6 range (see below)


tailscale.mode: "serve" - Enables Tailscale serve integration


Find Your IPv6 Range: Run tailscale status and look for IPv6 addresses starting with fd7a. Use that /48 prefix.

Step 2: Restart Clawdbot

clawdbot gateway restart
Step 3: Enable Tailscale Serve

First time setup requires authorization:
tailscale serve --bg --yes 18789
If you get a "Serve is not enabled" error:

Visit the authorization URL shown in the error message
Approve Tailscale Serve for your machine
Retry the command above

Verify it's working:
tailscale serve status
Should show:
https://your-machine.tail[XXXXX].ts.net (tailnet only)
|-- / proxy http://127.0.0.1:18789


Device Pairing Workflow

First-Time Remote Access


Attempt to connect via your Tailscale URL: https://your-machine.tail[XXXXX].ts.net
You'll see "pairing required" - this is expected!
Access locally to approve: http://127.0.0.1:18789
Navigate to device management in the UI and approve the pending pairing request
Refresh the remote browser - connection should now work

Subsequent Access

Once a device is paired, it connects immediately without further approval needed.

Security Model

Two-Layer Protection

Layer 1: Network (Tailscale)

Only devices on your Tailscale network can reach the gateway
End-to-end encrypted WireGuard connections
Managed via Tailscale ACLs and device authentication

Layer 2: Application (Clawdbot Device Pairing)

Each browser/device must be explicitly approved
Prevents unauthorized access even from compromised Tailscale devices
Maintains control over who can use your AI assistant

Why Loopback + Tailscale Serve?

Benefits:

✅ No direct network exposure (gateway invisible on LAN)
✅ Tailscale handles encryption automatically
✅ No port forwarding or firewall configuration needed
✅ Works from anywhere on your Tailscale network
✅ No public IP exposure

Alternative (Not Recommended):

bind: "lan" + manual firewall + gateway auth tokens
More complex, less secure, harder to maintain


Troubleshooting

Gateway Won't Start

Check configuration:
clawdbot doctor
clawdbot doctor --fix  # Auto-repair common issues
Common problems:

Invalid JSON syntax in config file
Port 18789 already in use by another service
Missing or incorrect Tailscale configuration

"Pairing Required" Persists

Check for pending requests:
cat ~/.clawdbot/devices/pending.json
Approve via local UI:

Access http://127.0.0.1:18789 from the same machine
Look for device management/pairing section
Approve any pending requests

Verify device is paired:
cat ~/.clawdbot/devices/paired.json
Tailscale Serve Issues

Verify Tailscale status:
tailscale status
Check/reconfigure serve:
tailscale serve status
# If needed, reset and reconfigure:
tailscale serve --https=443 off
tailscale serve --bg --yes 18789
Remote IP Not Recognized

Ensure your trustedProxies includes the correct Tailscale IP ranges:
Find your ranges:
tailscale status
# Look for IP addresses:
# IPv4: typically 100.x.x.x
# IPv6: typically fd7a:115c:a1e0::xxxx
Update the config with your specific IPv6 range.

Verification Commands

Health Check

clawdbot gateway status
clawdbot status --all
Test Local Access

curl http://127.0.0.1:18789/
# Should return HTML (the control UI)
Test Remote Access

Open: https://your-machine.tail[XXXXX].ts.net

First time: Shows pairing requirement
After approval: Full access to control UI

Logs

# Live gateway logs
tail -f ~/.clawdbot/logs/gateway.log

# Error logs
tail -f ~/.clawdbot/logs/gateway.err.log

Quick Reference

Important URLs


Local access: http://127.0.0.1:18789/
Tailscale access: https://your-machine.tail[XXXXX].ts.net/
Find your URL: tailscale serve status

Key Commands

# Gateway management
clawdbot gateway status
clawdbot gateway restart
clawdbot doctor

# Tailscale
tailscale status
tailscale serve status
tailscale serve --bg --yes 18789

# Logs & diagnostics
clawdbot logs --follow
clawdbot status --all
Configuration Files


Main config: ~/.clawdbot/clawdbot.json
Device pairings: ~/.clawdbot/devices/
Logs: ~/.clawdbot/logs/


Next Steps


Set up mobile access - Your Tailscale mobile app can now reach the assistant
Configure additional channels - WhatsApp, Telegram, Discord, etc.
Review security settings - Run clawdbot security audit regularly
Backup your config - Keep clawdbot.json and devices/ folders backed up


Troubleshooting Checklist

When things go wrong, check these in order:

 Gateway is running: clawdbot gateway status
 Tailscale is connected: tailscale status
 Serve is configured: tailscale serve status
 Config is valid: clawdbot doctor
 No port conflicts: lsof -i :18789
 Permissions are correct: ls -la ~/.clawdbot/
 Recent logs: tail -f ~/.clawdbot/logs/gateway.err.log


Notes

This guide covers the beta version of Clawdbot (2026.1.24-3). Configuration options and steps may change as the software stabilizes.
Found this helpful? Consider contributing improvements back to the official Clawdbot documentation.
Issues? Check the Clawdbot docs and community resources for updates.

Created by the community - Last updated: January 2026%
No results found