Clawdbot Ansible Installer

Automated, hardened installation of Clawdbot with Docker, Homebrew, and Tailscale VPN support for Linux and macOS.

Features

• 🔒 Firewall-first: UFW (Linux) + Application Firewall (macOS) + Docker isolation
• 🔐 Tailscale VPN: Secure remote access without exposing services
• 🍺 Homebrew: Package manager for both Linux and macOS
• 🐳 Docker: Docker CE (Linux) / Docker Desktop (macOS)
• 🛡️ Multi-OS Support: Debian, Ubuntu, and macOS
• 🚀 One-command install: Complete setup in minutes
• 🔧 Auto-configuration: DBus, systemd, environment setup
• 📦 pnpm installation: Uses pnpm install -g clawdbot@latest

Quick Start

Release Mode (Recommended)

Install the latest stable version from npm:

curl -fsSL https://raw.githubusercontent.com/pasogott/clawdbot-ansible/main/install.sh | bash

Development Mode

Install from source for development or testing:

# Clone the installer
git clone https://github.com/pasogott/clawdbot-ansible.git
cd clawdbot-ansible

# Install in development mode
ansible-playbook playbook.yml --ask-become-pass -e clawdbot_install_mode=development

What Gets Installed

• Tailscale (mesh VPN)
• UFW firewall (SSH + Tailscale ports only)
• Docker CE + Compose V2 (for sandboxes)
• Node.js 22.x + pnpm
• Clawdbot on host (not containerized)
• Systemd service (auto-start)

Post-Install

After installation completes, switch to the clawdbot user:

sudo su - clawdbot

Then run the quick-start onboarding wizard:

clawdbot onboard --install-daemon

This will:

• Guide you through the setup wizard
• Configure your messaging provider (WhatsApp/Telegram/Signal)
• Install and start the daemon service

Alternative Manual Setup

# Configure manually
clawdbot configure

# Login to provider
clawdbot providers login

# Test gateway
clawdbot gateway

# Install as daemon
clawdbot daemon install
clawdbot daemon start

# Check status
clawdbot status
clawdbot logs

Installation Modes

Release Mode (Default)

• Installs via pnpm install -g clawdbot@latest
• Gets latest stable version from npm registry
• Automatic updates via pnpm install -g clawdbot@latest
• Recommended for production

Development Mode

• Clones from https://github.com/clawdbot/clawdbot.git
• Builds from source with pnpm build
• Symlinks binary to ~/.local/bin/clawdbot
• Adds helpful aliases:
  • clawdbot-rebuild - Rebuild after code changes
  • clawdbot-dev - Navigate to repo directory
  • clawdbot-pull - Pull, install deps, and rebuild
• Recommended for development and testing

Enable with: -e clawdbot_install_mode=development

Security

• Public ports: SSH (22), Tailscale (41641/udp) only
• Docker available: For Clawdbot sandboxes (isolated execution)
• Docker isolation: Containers can't expose ports externally (DOCKER-USER chain)
• Non-root: Clawdbot runs as unprivileged user
• Systemd hardening: NoNewPrivileges, PrivateTmp

Verify: nmap -p- YOUR_SERVER_IP should show only port 22 open.

Documentation

• Security Architecture
• Technical Details
• Troubleshooting
• Agent Guidelines

Requirements

Linux (Debian/Ubuntu)

• Debian 11+ or Ubuntu 20.04+
• Root/sudo access
• Internet connection

macOS

• macOS 11 (Big Sur) or later
• Homebrew will be installed automatically
• Admin/sudo access
• Internet connection

What Gets Installed

Common (All OS)

• Homebrew package manager
• Node.js 22.x + pnpm
• Clawdbot via pnpm install -g clawdbot@latest
• Essential development tools
• Git, zsh, oh-my-zsh

Linux-Specific

• Docker CE + Compose V2
• UFW firewall (configured)
• Tailscale VPN
• systemd service

macOS-Specific

• Docker Desktop (via Homebrew Cask)
• Application Firewall
• Tailscale app

Manual Installation

Release Mode (Default)

# Install dependencies
sudo apt update && sudo apt install -y ansible git

# Clone repository
git clone https://github.com/pasogott/clawdbot-ansible.git
cd clawdbot-ansible

# Install Ansible collections
ansible-galaxy collection install -r requirements.yml

# Run installation
./run-playbook.sh

Development Mode

Build from source for development:

# Same as above, but with development mode flag
./run-playbook.sh -e clawdbot_install_mode=development

# Or directly:
ansible-playbook playbook.yml --ask-become-pass -e clawdbot_install_mode=development

This will:

• Clone clawdbot repo to ~/code/clawdbot
• Run pnpm install and pnpm build
• Symlink binary to ~/.local/bin/clawdbot
• Add development aliases to .bashrc

License

MIT - see LICENSE

Support

• Clawdbot: https://github.com/clawdbot/clawdbot
• This installer: https://github.com/pasogott/clawdbot-ansible/issues