From 258184232d9c043a94719f1c9a431a1e26cc7939 Mon Sep 17 00:00:00 2001 From: AG Date: Thu, 8 Jan 2026 23:06:52 -0800 Subject: [PATCH] docs: add Hetzner deployment guide --- docs/platforms/hetzner.md | 277 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 docs/platforms/hetzner.md diff --git a/docs/platforms/hetzner.md b/docs/platforms/hetzner.md new file mode 100644 index 000000000..3bdb9f688 --- /dev/null +++ b/docs/platforms/hetzner.md @@ -0,0 +1,277 @@ +--- +summary: "Run Clawdbot Gateway on Hetzner (Docker + VPS) with durable state and baked-in binaries" +read_when: + - You want a production-grade, always-on Gateway on your own VPS + - You want full control over persistence, binaries, and restart behavior + - You are running Clawdbot in Docker on Hetzner or a similar provider +--- + +# Clawdbot on Hetzner (Docker, Production VPS Guide) + +## Goal +Run a persistent Clawdbot Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior. + +The Gateway can be accessed via: +- SSH port forwarding from your laptop +- Direct port exposure if you manage firewalling and tokens yourself + +This guide assumes Ubuntu or Debian on Hetzner. +If you are on another Linux VPS, map packages accordingly. + +--- + +## Quick path (experienced operators) + +1) Provision Hetzner VPS +2) Install Docker +3) Clone Clawdbot repository +4) Create persistent host directories +5) Configure `.env` and `docker-compose.yml` +6) Bake required binaries into the image +7) `docker compose up -d` +8) Verify persistence and Gateway access + +--- + +## What you need + +- Hetzner VPS with root access +- SSH access from your laptop +- Docker and Docker Compose +- Model auth credentials +- Optional provider credentials + - WhatsApp QR + - Telegram bot token + - Gmail OAuth + +--- + +## 1) Provision the VPS + +Create an Ubuntu or Debian VPS in Hetzner. + +Connect as root: + +```bash +ssh root@YOUR_VPS_IP +``` + +This guide assumes the VPS is stateful. +Do not treat it as disposable infrastructure. + +--- + +## 2) Install Docker (on the VPS) + +```bash +apt-get update +apt-get install -y git curl ca-certificates +curl -fsSL https://get.docker.com | sh +``` + +Verify: + +```bash +docker --version +docker compose version +``` + +--- + +## 3) Clone the Clawdbot repository + +```bash +git clone https://github.com/clawdbot/clawdbot.git +cd clawdbot +``` + +This guide assumes you will build a custom image to guarantee binary persistence. + +--- + +## 4) Create persistent host directories + +Docker containers are ephemeral. +All long-lived state must live on the host. + +```bash +mkdir -p /root/.clawdbot +mkdir -p /root/clawd + +# Set ownership to the container user (uid 1000): +chown -R 1000:1000 /root/.clawdbot +chown -R 1000:1000 /root/clawd +``` + +--- + +## 5) Configure environment variables + +Create `.env` in the repository root. + +```bash +CLAWDBOT_IMAGE=clawdbot:latest +CLAWDBOT_GATEWAY_TOKEN=change-me-now +CLAWDBOT_GATEWAY_PORT=18789 + +CLAWDBOT_CONFIG_DIR=/root/.clawdbot +CLAWDBOT_WORKSPACE_DIR=/root/clawd + +GOG_KEYRING_PASSWORD=change-me-now +XDG_CONFIG_HOME=/home/node/.clawdbot +``` + +**Do not commit this file.** + +--- + +## 6) Docker Compose configuration + +Create or update `docker-compose.yml`. + +```yaml +services: + clawdbot-gateway: + image: ${CLAWDBOT_IMAGE} + restart: unless-stopped + env_file: + - .env + environment: + - NODE_ENV=production + - TERM=xterm-256color + - CLAWDBOT_GATEWAY_TOKEN=${CLAWDBOT_GATEWAY_TOKEN} + - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD} + - XDG_CONFIG_HOME=${XDG_CONFIG_HOME} + - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + volumes: + - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot + - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd + ports: + - "${CLAWDBOT_GATEWAY_PORT}:18789" + - "18793:18793" +``` + +--- + +## 7) Bake required binaries into the image (critical) + +Installing binaries inside a running container is a trap. +Anything installed at runtime will be lost on restart. + +All external binaries required by skills must be installed at image build time. + +The examples below show three common binaries only: +- `gog` for Gmail access +- `goplaces` for Google Places +- `wacli` for WhatsApp + +These are examples, not a complete list. +You may install as many binaries as needed using the same pattern. + +If you add new skills later that depend on additional binaries, you must: +1. Update the Dockerfile +2. Rebuild the image +3. Restart the containers + +**Example Dockerfile** + +```dockerfile +FROM node:22-bookworm + +RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/* + +# Example binary 1: Gmail CLI +RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \ + | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog + +# Example binary 2: Google Places CLI +RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \ + | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces + +# Example binary 3: WhatsApp CLI +RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \ + | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli + +# Add more binaries below using the same pattern + +WORKDIR /app +COPY . . +RUN corepack enable +RUN pnpm install --frozen-lockfile +RUN pnpm build +RUN pnpm ui:install +RUN pnpm ui:build + +CMD ["node","dist/index.js"] +``` + +--- + +## 8) Build and launch + +```bash +docker compose build clawdbot-gateway +docker compose up -d +``` + +Verify binaries: + +```bash +docker exec clawdbot-clawdbot-gateway-1 which gog +docker exec clawdbot-clawdbot-gateway-1 which goplaces +docker exec clawdbot-clawdbot-gateway-1 which wacli +``` + +Expected output: + +``` +/usr/local/bin/gog +/usr/local/bin/goplaces +/usr/local/bin/wacli +``` + +--- + +## 9) Verify Gateway + +```bash +docker logs -f clawdbot-clawdbot-gateway-1 +``` + +Success: + +``` +[gateway] listening on ws://0.0.0.0:18789 +``` + +From your laptop: + +```bash +ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP +``` + +Open: + +`http://127.0.0.1:18789/` + +Paste your gateway token. + +--- + +## What persists where (source of truth) + +Clawdbot runs in Docker, but Docker is not the source of truth. +All long-lived state must survive restarts, rebuilds, and reboots. + +| Component | Location | Persistence mechanism | Notes | +|---|---|---|---| +| Gateway config | `/home/node/.clawdbot/` | Host volume mount | Includes `clawdbot.json`, tokens | +| Model auth profiles | `/home/node/.clawdbot/` | Host volume mount | OAuth tokens, API keys | +| Skill configs | `/home/node/.clawdbot/skills/` | Host volume mount | Skill-level state | +| Agent workspace | `/home/node/clawd/` | Host volume mount | Code and agent artifacts | +| WhatsApp session | `/home/node/.clawdbot/` | Host volume mount | Preserves QR login | +| Gmail keyring | `/home/node/.clawdbot/` | Host volume + password | Requires `GOG_KEYRING_PASSWORD` | +| External binaries | `/usr/local/bin/` | Docker image | Must be baked at build time | +| Node runtime | Container filesystem | Docker image | Rebuilt every image build | +| OS packages | Container filesystem | Docker image | Do not install at runtime | +| Docker container | Ephemeral | Restartable | Safe to destroy |