Clawdbot Secure Installation Guide

This repository contains scripts to securely install and configure Clawdbot on Ubuntu 22.04 with comprehensive security hardening.

Features

• ✅ Docker-based Clawdbot installation
• ✅ Gateway binds to localhost only (127.0.0.1) - NOT publicly accessible
• ✅ Password authentication with strong password requirements (16+ chars)
• ✅ Tailscale integration for secure remote access
• ✅ UFW firewall configured (SSH + Tailscale only, blocks everything else)
• ✅ Fail2ban for SSH brute force protection
• ✅ Unattended security updates enabled
• ✅ Non-root user for running Clawdbot
• ✅ Log rotation configured
• ✅ DM policy set to pairing (not open)
• ✅ Channel allowlist configured (not open)
• ✅ Idempotent - safe to run multiple times
• ✅ Reversible - complete uninstall instructions included

Quick Start (One-Line Command)

Required Environment Variables

export CLAWDBOT_PASSWORD="your-strong-password-min-16-chars"
export TAILSCALE_AUTH_KEY="tskey-auth-xxxxx"  # Optional but recommended

Installation

curl -fsSL https://raw.githubusercontent.com/yourusername/yourrepo/main/install_and_harden.sh | sudo -E bash

Or download and run locally:

wget https://raw.githubusercontent.com/yourusername/yourrepo/main/install_and_harden.sh
chmod +x install_and_harden.sh
export CLAWDBOT_PASSWORD="your-strong-password-min-16-chars"
export TAILSCALE_AUTH_KEY="tskey-auth-xxxxx"  # Optional
sudo -E ./install_and_harden.sh

Manual Installation Steps

1. Prepare Environment Variables

Create a secure password (minimum 16 characters):

export CLAWDBOT_PASSWORD="$(openssl rand -base64 24)"
echo "Your Clawdbot password: $CLAWDBOT_PASSWORD"
# SAVE THIS PASSWORD SECURELY!

Get a Tailscale auth key from: https://login.tailscale.com/admin/settings/keys

export TAILSCALE_AUTH_KEY="tskey-auth-xxxxx"

2. Run Installation Script

sudo -E ./install_and_harden.sh

The script will:

• Update system packages
• Install Docker, UFW, Fail2ban, Tailscale
• Create a non-root clawdbot user
• Configure firewall (SSH + Tailscale only)
• Enable unattended security updates
• Install and configure Clawdbot with secure defaults
• Run a health check

3. Access Clawdbot

Option A: Tailscale Serve (Recommended)

cd /home/clawdbot/clawdbot
sudo ./setup-tailscale-serve.sh

Access at: https://<hostname>.<tailnet>.ts.net

Option B: SSH Tunnel

From your local machine:

ssh -L 3000:127.0.0.1:3000 ubuntu@<server-ip>

Access at: http://localhost:3000

Login with your CLAWDBOT_PASSWORD.

Security Architecture

Network Security

• Gateway Binding: Clawdbot gateway binds to 127.0.0.1:3000 only (not 0.0.0.0)
• No Public Ports: Port 3000 is NOT exposed to the internet
• UFW Firewall: Only SSH (22) and Tailscale (41641/udp) are allowed
• Access Methods: Only via Tailscale Serve or SSH tunnel

Authentication & Authorization

• Auth Mode: Password-based authentication (required)
• Strong Password: Minimum 16 characters enforced
• DM Policy: Set to pairing (not open)
• Channel Allowlist: Configured (not open to all)

System Hardening

• Non-Root User: Clawdbot runs as dedicated clawdbot user
• Fail2ban: Protects SSH from brute force attacks (3 attempts, 2-hour ban)
• Unattended Upgrades: Automatic security updates enabled
• Log Rotation: Prevents disk space exhaustion
• Docker Isolation: Clawdbot runs in isolated container

Management Commands

Check Status

sudo systemctl status clawdbot
docker ps

View Logs

docker logs clawdbot -f

Restart Service

sudo systemctl restart clawdbot

Stop Service

sudo systemctl stop clawdbot

Health Check

cd /home/clawdbot/clawdbot
./clawdbot-doctor.sh

Update Clawdbot

cd /home/clawdbot/clawdbot
docker-compose pull
sudo systemctl restart clawdbot

Configuration

Configuration file: /home/clawdbot/clawdbot/.env

Important: Never commit .env to git! It contains your password.

To change settings:

sudo nano /home/clawdbot/clawdbot/.env
sudo systemctl restart clawdbot

Troubleshooting

Clawdbot not starting

docker logs clawdbot
sudo systemctl status clawdbot

Can't access via Tailscale

sudo tailscale status
sudo tailscale up  # Re-authenticate if needed

Firewall blocking connections

sudo ufw status verbose

Check all security settings

cd /home/clawdbot/clawdbot
./clawdbot-doctor.sh

Uninstall / Rollback

See /home/clawdbot/clawdbot/UNINSTALL.md for complete removal instructions.

Quick Uninstall

sudo systemctl stop clawdbot
sudo systemctl disable clawdbot
cd /home/clawdbot/clawdbot
docker-compose down -v
sudo userdel -r clawdbot
sudo rm /etc/systemd/system/clawdbot.service
sudo systemctl daemon-reload

Files Included

• install_and_harden.sh - Main installation script (idempotent)
• docker-compose.yml - Docker Compose configuration (generated)
• .env - Environment variables with secrets (generated, not in git)
• README.md - This file
• UNINSTALL.md - Removal instructions (generated)
• clawdbot-doctor.sh - Health check script (generated)
• setup-tailscale-serve.sh - Tailscale Serve setup (generated)

Security Best Practices

1. Never commit secrets to git - .env file is excluded
2. Use strong passwords - Minimum 16 characters enforced
3. Keep system updated - Unattended upgrades enabled
4. Monitor logs - Check docker logs clawdbot regularly
5. Run health checks - Use clawdbot-doctor.sh periodically
6. Limit access - Only use Tailscale or SSH tunnel, never expose publicly
7. Review firewall rules - sudo ufw status verbose
8. Check Fail2ban - sudo fail2ban-client status sshd

Requirements

• Ubuntu 22.04 LTS (fresh installation recommended)
• Root or sudo access
• Internet connection
• Tailscale account (optional but recommended)

License

This script is provided as-is for secure Clawdbot deployment.

Support

For issues with:

• This script: Open an issue in this repository
• Clawdbot: See official Clawdbot documentation
• Tailscale: See https://tailscale.com/kb/

Changelog

• v1.0.0 - Initial release with full security hardening