Before You Start

This guide works on any Ubuntu VPS with SSH access. The commands are provider-agnostic.

Tip: I like Hostinger for this setup because they offer an MCP (Model Context Protocol) tool that allows Claude Code to manage server configurations, firewalls, and deployments directly.

Phase 1: Assess Your VPS

1.1 Create a VPS Snapshot

Before making any changes, create a snapshot in your VPS control panel for rollback safety.

1.2 Check Current Node.js Version

Clawdbot requires Node.js v22+. First, check what version (if any) is installed:

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "node --version 2>/dev/null || echo 'Node.js not installed'"

1.3 Install or Upgrade Node.js

If Node.js is not installed or is below v22:

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt-get install -y nodejs"

Verify the installation:

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "node --version"

You should see v22.x.x or higher.

Phase 2: Install Tailscale

Tailscale creates a secure mesh VPN so Clawdbot is only accessible to your devices - not the public internet.

2.1 Install Tailscale

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "curl -fsSL https://tailscale.com/install.sh | sh"

2.2 Connect to Your Tailnet

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "tailscale up"

This outputs an authentication URL. Open it in your browser and approve the device.

2.3 Get Your Tailscale IP

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "tailscale ip -4"

Save this IP (format: 100.x.x.x) - you will need it for gateway configuration.

2.4 Get Your Tailscale DNS Name

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "tailscale status --json | jq -r '.Self.DNSName' | sed 's/\.$//'"

Save this (format: your-vps.tail1234.ts.net) - this becomes your HTTPS URL.

Phase 3: Install Clawdbot

3.1 Install Clawdbot Globally

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "npm install -g clawdbot@latest"

3.2 Install Claude Code CLI

Clawdbot routes messages to Claude Code CLI, which does the actual AI processing:

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "npm install -g @anthropic-ai/claude-code"

3.3 Run Clawdbot Onboard

This configures the gateway to only listen on your Tailscale IP (secure):

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "clawdbot onboard --non-interactive --accept-risk --gateway-bind tailnet --gateway-auth token"

IMPORTANT: Save the gateway token displayed! You need it to access the Control UI.

3.4 Create Agent Configuration

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "mkdir -p ~/.clawdbot/agents/main && cat > ~/.clawdbot/agents/main/agent.yaml << 'EOF'
name: main
description: Primary Clawdbot agent
model: claude-opus-4-5
workspace: /root/clawd
EOF"

Phase 4: Configure Claude Pro Authentication

Clawdbot uses your Claude Pro subscription via OAuth tokens.

4.1 Generate OAuth Token

On your LOCAL machine (Windows/Mac) with Claude Code installed:

claude setup-token

Follow the browser prompts to authenticate with your Claude Pro account.

4.2 Copy Auth Credentials to VPS

# Create directories on VPS
ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "mkdir -p ~/.claude ~/.clawdbot/agents/main/agent"
Copy auth file (run from your local machine)
scp -i YOUR_KEY ~/.claude/auth-profiles.json root@YOUR_IP:~/.claude/
scp -i YOUR_KEY ~/.claude/auth-profiles.json root@YOUR_IP:~/.clawdbot/agents/main/agent/

4.3 Restart Gateway to Load Auth

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "systemctl --user restart clawdbot-gateway"

Phase 5: Enable HTTPS Access via Tailscale Serve

Browsers require HTTPS for WebSocket connections. Tailscale Serve provides automatic SSL certificates.

5.1 Enable Tailscale Serve

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "tailscale serve --bg http://TAILSCALE_IP:18789"

Replace TAILSCALE_IP with your Tailscale IP from Phase 2.3.

If you see "Serve is not enabled", click the URL shown to enable it in your Tailscale admin console.

5.2 Your Control UI URL

Your Clawdbot Control UI is now available at:

https://YOUR-TAILSCALE-DNS/?token=YOUR_GATEWAY_TOKEN

Replace with your values from Phase 2.4 and Phase 3.3.

Phase 6: First Access and Device Pairing

6.1 Open the Control UI

Open your HTTPS URL in a browser. You will likely see a "pairing required" error.

6.2 Approve Your Browser

List pending device pairing requests:

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "clawdbot devices list"

Approve your browser (copy the Request UUID from the pending list):

ssh -i YOUR_KEY -o BatchMode=yes root@YOUR_IP "clawdbot devices approve REQUEST_UUID"

6.3 Test It!

Refresh the Control UI page. You should now be connected. Send a test message like "Hello, what time is it?" to verify the AI responds.

Troubleshooting

Error: spawnSync claude ENOENT

Claude Code CLI is not installed. Install it:

ssh root@YOUR_IP "npm install -g @anthropic-ai/claude-code"

Error: secure context required

You are accessing via HTTP instead of HTTPS. Use the Tailscale Serve URL (https://...ts.net/), not the direct IP.

Error: pairing required

Your browser needs to be approved. Run clawdbot devices list and clawdbot devices approve REQUEST_UUID.

Error: disconnected

Check if the gateway is running:

ssh root@YOUR_IP "systemctl --user status clawdbot-gateway"

General Health Check

ssh root@YOUR_IP "clawdbot doctor"

This shows auth status, agent configuration, and any issues.