Deploy ClawButler on Your Own Machine

One-Click Install (Recommended)#

A single command handles environment detection, dependency installation, secret generation, and service startup. Supports Linux and macOS.

curl -fsSL https://raw.githubusercontent.com/Octo-o-o-o/clawbutler/main/scripts/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/Octo-o-o-o/clawbutler/main/scripts/install.sh | QUICK=1 bash

The install script automates: system check → Docker verification → clone repo → auto-detect local OpenClaw → generate secrets → port conflict detection → build & start services → run migrations → health check → install management CLI

Management CLI (clawbutlerctl)#

The installer automatically places clawbutlerctl in /usr/local/bin. Common management commands:

Manual Setup (Developers)#

For finer-grained control or development mode, follow these manual steps.

Prerequisites#

You need four tools: Docker (for databases), Node.js 22+ (for Web frontend), pnpm (package manager), and uv (Python environment manager). Install instructions for each platform below.

# 1. Docker Desktop → docker.com/products/docker-desktop/ (download & install)
# 2. Node.js 22 LTS → nodejs.org (download & install)
# 3. pnpm
npm install -g pnpm
# 4. uv (Python package manager — auto-installs Python 3.12)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Restart PowerShell after install, or refresh PATH:
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"

# 1. Docker Desktop → docker.com/products/docker-desktop/ (Apple Silicon / Intel)
#    Alternative: OrbStack (orbstack.dev) — lighter resource usage
# 2. Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 3. Node.js 22+
brew install node@22
# 4. pnpm
npm install -g pnpm
# 5. uv (Python package manager — auto-installs Python 3.12)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env   # refresh PATH

# 1. Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker
# 2. Node.js 22+ (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Fedora: sudo dnf install -y nodejs
# Arch:   sudo pacman -S nodejs npm
# 3. pnpm
npm install -g pnpm
# 4. uv (Python package manager — auto-installs Python 3.12)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env   # refresh PATH

Verify Environment#

Run these commands to confirm all tools are ready:

docker --version          # Docker 20+
docker info 2>&1 | grep "Server Version"   # confirms daemon is running
node --version            # v22.x.x+
pnpm --version            # 10.x.x+
uv --version              # 0.6.x+

If uv is not found: Windows — restart PowerShell or run $env:Path refresh; macOS/Linux — run source $HOME/.local/bin/env or restart your terminal.

Daily Usage#

After rebooting, start services in 3 separate terminals:

# Terminal 1: Start databases (if not running)
docker compose -f deploy/docker-compose.dev.yml up -d

# Terminal 2: Start API (from project-root/apps/)
cd apps
uv run --project api uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 3: Start Web (from project-root/apps/web/)
cd apps/web
pnpm dev

To stop: press Ctrl+C in the API and Web terminals. For databases: docker compose -f deploy/docker-compose.dev.yml down (data is preserved in Docker Volumes).

Production Configuration#

For production deployment, generate secure secrets and configure these environment variables in your .env file:

SMTP_HOST is required in production mode. Recommended: Resend (free 100 emails/day).

Production HTTPS (Caddy)#

Recommended: use Caddy for automatic Let's Encrypt certificates. Install via apt/yum on Linux, brew on macOS.

# Install Caddy
# Linux (Debian/Ubuntu): sudo apt install caddy
# Linux (RHEL/Fedora):   sudo dnf install caddy
# macOS:                 brew install caddy
# Windows:               choco install caddy (or scoop install caddy)

# Edit Caddyfile
# Linux:  sudo nano /etc/caddy/Caddyfile
# macOS:  nano /opt/homebrew/etc/Caddyfile

your-domain.com {
    handle /api/auth/* { reverse_proxy localhost:3000 }
    handle /api/*      { reverse_proxy localhost:8000 }
    handle /health     { reverse_proxy localhost:8000 }
    handle /docs       { reverse_proxy localhost:8000 }
    handle             { reverse_proxy localhost:3000 }
}

# Production: bind ports to 127.0.0.1
docker compose -f docker-compose.yml \
  -f deploy/docker-compose.production.yml up -d --build

sudo systemctl enable caddy && sudo systemctl start caddy

System Requirements#

Operations#

# Recommended: use management CLI
clawbutlerctl update

# Or manually:
cd ~/clawbutler && git pull
docker compose build && docker compose up -d

docker compose exec -T postgres \
  pg_dump -U postgres agentplanet \
  | gzip > backup_$(date +%Y%m%d).sql.gz

Cloud Connection#

Connect your self-hosted OpenClaw to ClawButler Cloud (clawbutler.cc) for remote management, chat, and monitoring — without exposing any local ports to the internet.

Cloud (clawbutler.cc)              Your Machine
┌──────────────────┐               ┌──────────────────┐
│  ClawButler API  │   WSS (443)   │  Edge Agent      │
│  ◄════════════════════════════►  │    ↕              │
│  Dashboard / Chat│   outbound    │  OpenClaw Gateway │
└──────────────────┘   tunnel      │  (127.0.0.1:18789) │
                                   └──────────────────┘

curl -fsSL https://clawbutler.cc/install | bash -s -- --edge-only

cd ~/.clawbutler/edge-agent
python3 clawbutler_edge.py pair \
  --cloud-url https://clawbutler.cc \
  --openclaw-url ws://127.0.0.1:18789

python3 clawbutler_edge.py

Connection Security#

The Edge Agent is designed with a zero-inbound-port architecture. Your OpenClaw gateway never needs to be reachable from the internet.

Security Layers

Default Ports#

FAQ#