@gguf/pigbot 0.0.1 → 0.0.3

package/docs/platforms/gcp.md

@@ -0,0 +1,498 @@
+---
+summary: "Run Moltbot Gateway 24/7 on a GCP Compute Engine VM (Docker) with durable state"
+read_when:
+  - You want Moltbot running 24/7 on GCP
+  - You want a production-grade, always-on Gateway on your own VM
+  - You want full control over persistence, binaries, and restart behavior
+---
+
+# Moltbot on GCP Compute Engine (Docker, Production VPS Guide)
+
+## Goal
+
+Run a persistent Moltbot Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior.
+
+If you want "Moltbot 24/7 for ~$5-12/mo", this is a reliable setup on Google Cloud.
+Pricing varies by machine type and region; pick the smallest VM that fits your workload and scale up if you hit OOMs.
+
+## What are we doing (simple terms)?
+
+- Create a GCP project and enable billing
+- Create a Compute Engine VM
+- Install Docker (isolated app runtime)
+- Start the Moltbot Gateway in Docker
+- Persist `~/.clawdbot` + `~/clawd` on the host (survives restarts/rebuilds)
+- Access the Control UI from your laptop via an SSH tunnel
+
+The Gateway can be accessed via:
+- SSH port forwarding from your laptop
+- Direct port exposure if you manage firewalling and tokens yourself
+
+This guide uses Debian on GCP Compute Engine.
+Ubuntu also works; map packages accordingly.
+For the generic Docker flow, see [Docker](/install/docker).
+
+---
+
+## Quick path (experienced operators)
+
+1) Create GCP project + enable Compute Engine API
+2) Create Compute Engine VM (e2-small, Debian 12, 20GB)
+3) SSH into the VM
+4) Install Docker
+5) Clone Moltbot repository
+6) Create persistent host directories
+7) Configure `.env` and `docker-compose.yml`
+8) Bake required binaries, build, and launch
+
+---
+
+## What you need
+
+- GCP account (free tier eligible for e2-micro)
+- gcloud CLI installed (or use Cloud Console)
+- SSH access from your laptop
+- Basic comfort with SSH + copy/paste
+- ~20-30 minutes
+- Docker and Docker Compose
+- Model auth credentials
+- Optional provider credentials
+  - WhatsApp QR
+  - Telegram bot token
+  - Gmail OAuth
+
+---
+
+## 1) Install gcloud CLI (or use Console)
+
+**Option A: gcloud CLI** (recommended for automation)
+
+Install from https://cloud.google.com/sdk/docs/install
+
+Initialize and authenticate:
+
+```bash
+gcloud init
+gcloud auth login
+```
+
+**Option B: Cloud Console**
+
+All steps can be done via the web UI at https://console.cloud.google.com
+
+---
+
+## 2) Create a GCP project
+
+**CLI:**
+
+```bash
+gcloud projects create my-moltbot-project --name="Moltbot Gateway"
+gcloud config set project my-moltbot-project
+```
+
+Enable billing at https://console.cloud.google.com/billing (required for Compute Engine).
+
+Enable the Compute Engine API:
+
+```bash
+gcloud services enable compute.googleapis.com
+```
+
+**Console:**
+
+1. Go to IAM & Admin > Create Project
+2. Name it and create
+3. Enable billing for the project
+4. Navigate to APIs & Services > Enable APIs > search "Compute Engine API" > Enable
+
+---
+
+## 3) Create the VM
+
+**Machine types:**
+
+| Type | Specs | Cost | Notes |
+|------|-------|------|-------|
+| e2-small | 2 vCPU, 2GB RAM | ~$12/mo | Recommended |
+| e2-micro | 2 vCPU (shared), 1GB RAM | Free tier eligible | May OOM under load |
+
+**CLI:**
+
+```bash
+gcloud compute instances create moltbot-gateway \
+  --zone=us-central1-a \
+  --machine-type=e2-small \
+  --boot-disk-size=20GB \
+  --image-family=debian-12 \
+  --image-project=debian-cloud
+```
+
+**Console:**
+
+1. Go to Compute Engine > VM instances > Create instance
+2. Name: `moltbot-gateway`
+3. Region: `us-central1`, Zone: `us-central1-a`
+4. Machine type: `e2-small`
+5. Boot disk: Debian 12, 20GB
+6. Create
+
+---
+
+## 4) SSH into the VM
+
+**CLI:**
+
+```bash
+gcloud compute ssh moltbot-gateway --zone=us-central1-a
+```
+
+**Console:**
+
+Click the "SSH" button next to your VM in the Compute Engine dashboard.
+
+Note: SSH key propagation can take 1-2 minutes after VM creation. If connection is refused, wait and retry.
+
+---
+
+## 5) Install Docker (on the VM)
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl ca-certificates
+curl -fsSL https://get.docker.com | sudo sh
+sudo usermod -aG docker $USER
+```
+
+Log out and back in for the group change to take effect:
+
+```bash
+exit
+```
+
+Then SSH back in:
+
+```bash
+gcloud compute ssh moltbot-gateway --zone=us-central1-a
+```
+
+Verify:
+
+```bash
+docker --version
+docker compose version
+```
+
+---
+
+## 6) Clone the Moltbot repository
+
+```bash
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+```
+
+This guide assumes you will build a custom image to guarantee binary persistence.
+
+---
+
+## 7) Create persistent host directories
+
+Docker containers are ephemeral.
+All long-lived state must live on the host.
+
+```bash
+mkdir -p ~/.clawdbot
+mkdir -p ~/clawd
+```
+
+---
+
+## 8) Configure environment variables
+
+Create `.env` in the repository root.
+
+```bash
+CLAWDBOT_IMAGE=moltbot:latest
+CLAWDBOT_GATEWAY_TOKEN=change-me-now
+CLAWDBOT_GATEWAY_BIND=lan
+CLAWDBOT_GATEWAY_PORT=18789
+
+CLAWDBOT_CONFIG_DIR=/home/$USER/.clawdbot
+CLAWDBOT_WORKSPACE_DIR=/home/$USER/clawd
+
+GOG_KEYRING_PASSWORD=change-me-now
+XDG_CONFIG_HOME=/home/node/.clawdbot
+```
+
+Generate strong secrets:
+
+```bash
+openssl rand -hex 32
+```
+
+**Do not commit this file.**
+
+---
+
+## 9) Docker Compose configuration
+
+Create or update `docker-compose.yml`.
+
+```yaml
+services:
+  moltbot-gateway:
+    image: ${CLAWDBOT_IMAGE}
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOME=/home/node
+      - NODE_ENV=production
+      - TERM=xterm-256color
+      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
+      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
+      - 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:
+      # Recommended: keep the Gateway loopback-only on the VM; access via SSH tunnel.
+      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
+      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"
+
+      # Optional: only if you run iOS/Android nodes against this VM and need Canvas host.
+      # If you expose this publicly, read /gateway/security and firewall accordingly.
+      # - "18793:18793"
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${CLAWDBOT_GATEWAY_BIND}",
+        "--port",
+        "${CLAWDBOT_GATEWAY_PORT}"
+      ]
+```
+
+---
+
+## 10) 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 package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+---
+
+## 11) Build and launch
+
+```bash
+docker compose build
+docker compose up -d moltbot-gateway
+```
+
+Verify binaries:
+
+```bash
+docker compose exec moltbot-gateway which gog
+docker compose exec moltbot-gateway which goplaces
+docker compose exec moltbot-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+---
+
+## 12) Verify Gateway
+
+```bash
+docker compose logs -f moltbot-gateway
+```
+
+Success:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+---
+
+## 13) Access from your laptop
+
+Create an SSH tunnel to forward the Gateway port:
+
+```bash
+gcloud compute ssh moltbot-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
+```
+
+Open in your browser:
+
+`http://127.0.0.1:18789/`
+
+Paste your gateway token.
+
+---
+
+## What persists where (source of truth)
+
+Moltbot 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 `moltbot.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 |
+
+---
+
+## Updates
+
+To update Moltbot on the VM:
+
+```bash
+cd ~/moltbot
+git pull
+docker compose build
+docker compose up -d
+```
+
+---
+
+## Troubleshooting
+
+**SSH connection refused**
+
+SSH key propagation can take 1-2 minutes after VM creation. Wait and retry.
+
+**OS Login issues**
+
+Check your OS Login profile:
+
+```bash
+gcloud compute os-login describe-profile
+```
+
+Ensure your account has the required IAM permissions (Compute OS Login or Compute OS Admin Login).
+
+**Out of memory (OOM)**
+
+If using e2-micro and hitting OOM, upgrade to e2-small or e2-medium:
+
+```bash
+# Stop the VM first
+gcloud compute instances stop moltbot-gateway --zone=us-central1-a
+
+# Change machine type
+gcloud compute instances set-machine-type moltbot-gateway \
+  --zone=us-central1-a \
+  --machine-type=e2-small
+
+# Start the VM
+gcloud compute instances start moltbot-gateway --zone=us-central1-a
+```
+
+---
+
+## Service accounts (security best practice)
+
+For personal use, your default user account works fine.
+
+For automation or CI/CD pipelines, create a dedicated service account with minimal permissions:
+
+1. Create a service account:
+   ```bash
+   gcloud iam service-accounts create moltbot-deploy \
+     --display-name="Moltbot Deployment"
+   ```
+
+2. Grant Compute Instance Admin role (or narrower custom role):
+   ```bash
+   gcloud projects add-iam-policy-binding my-moltbot-project \
+     --member="serviceAccount:moltbot-deploy@my-moltbot-project.iam.gserviceaccount.com" \
+     --role="roles/compute.instanceAdmin.v1"
+   ```
+
+Avoid using the Owner role for automation. Use the principle of least privilege.
+
+See https://cloud.google.com/iam/docs/understanding-roles for IAM role details.
+
+---
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Pair local devices as nodes: [Nodes](/nodes)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)

package/docs/platforms/hetzner.md

@@ -1,26 +1,26 @@
 ---
-summary: "Run Pigbot Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
+summary: "Run Moltbot Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
 read_when:
-  - You want Pigbot running 24/7 on a cloud VPS (not your laptop)
+  - You want Moltbot running 24/7 on a cloud VPS (not your laptop)
   - 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 Pigbot in Docker on Hetzner or a similar provider
+  - You are running Moltbot in Docker on Hetzner or a similar provider
 ---
 
-# Pigbot on Hetzner (Docker, Production VPS Guide)
+# Moltbot on Hetzner (Docker, Production VPS Guide)
 
 ## Goal
-Run a persistent Pigbot Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
+Run a persistent Moltbot Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
 
-If you want “Pigbot 24/7 for ~$5”, this is the simplest reliable setup.
+If you want “Moltbot 24/7 for ~$5”, this is the simplest reliable setup.
 Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.
 
 ## What are we doing (simple terms)?
 
 - Rent a small Linux server (Hetzner VPS)
 - Install Docker (isolated app runtime)
-- Start the Pigbot Gateway in Docker
-- Persist `~/.pigbot` + `~/clawd` on the host (survives restarts/rebuilds)
+- Start the Moltbot Gateway in Docker
+- Persist `~/.clawdbot` + `~/clawd` on the host (survives restarts/rebuilds)
 - Access the Control UI from your laptop via an SSH tunnel
 
 The Gateway can be accessed via:
@@ -37,7 +37,7 @@ For the generic Docker flow, see [Docker](/install/docker).
 
 1) Provision Hetzner VPS  
 2) Install Docker  
-3) Clone Pigbot repository  
+3) Clone Moltbot repository  
 4) Create persistent host directories  
 5) Configure `.env` and `docker-compose.yml`  
 6) Bake required binaries into the image  
@@ -93,11 +93,11 @@ docker compose version
 
 ---
 
-## 3) Clone the Pigbot repository
+## 3) Clone the Moltbot repository
 
 ```bash
-git clone https://github.com/pigbot/pigbot.git
-cd pigbot
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
 ```
 
 This guide assumes you will build a custom image to guarantee binary persistence.
@@ -110,11 +110,11 @@ Docker containers are ephemeral.
 All long-lived state must live on the host.
 
 ```bash
-mkdir -p /root/.pigbot
+mkdir -p /root/.clawdbot
 mkdir -p /root/clawd
 
 # Set ownership to the container user (uid 1000):
-chown -R 1000:1000 /root/.pigbot
+chown -R 1000:1000 /root/.clawdbot
 chown -R 1000:1000 /root/clawd
 ```
 
@@ -125,16 +125,16 @@ chown -R 1000:1000 /root/clawd
 Create `.env` in the repository root.
 
 ```bash
-PIGBOT_IMAGE=pigbot:latest
-PIGBOT_GATEWAY_TOKEN=change-me-now
-PIGBOT_GATEWAY_BIND=lan
-PIGBOT_GATEWAY_PORT=18789
+CLAWDBOT_IMAGE=moltbot:latest
+CLAWDBOT_GATEWAY_TOKEN=change-me-now
+CLAWDBOT_GATEWAY_BIND=lan
+CLAWDBOT_GATEWAY_PORT=18789
 
-PIGBOT_CONFIG_DIR=/root/.pigbot
-PIGBOT_WORKSPACE_DIR=/root/clawd
+CLAWDBOT_CONFIG_DIR=/root/.clawdbot
+CLAWDBOT_WORKSPACE_DIR=/root/clawd
 
 GOG_KEYRING_PASSWORD=change-me-now
-XDG_CONFIG_HOME=/home/node/.pigbot
+XDG_CONFIG_HOME=/home/node/.clawdbot
 ```
 
 Generate strong secrets:
@@ -153,8 +153,8 @@ Create or update `docker-compose.yml`.
 
 ```yaml
 services:
-  pigbot-gateway:
-    image: ${PIGBOT_IMAGE}
+  moltbot-gateway:
+    image: ${CLAWDBOT_IMAGE}
     build: .
     restart: unless-stopped
     env_file:
@@ -163,19 +163,19 @@ services:
       - HOME=/home/node
       - NODE_ENV=production
       - TERM=xterm-256color
-      - PIGBOT_GATEWAY_BIND=${PIGBOT_GATEWAY_BIND}
-      - PIGBOT_GATEWAY_PORT=${PIGBOT_GATEWAY_PORT}
-      - PIGBOT_GATEWAY_TOKEN=${PIGBOT_GATEWAY_TOKEN}
+      - CLAWDBOT_GATEWAY_BIND=${CLAWDBOT_GATEWAY_BIND}
+      - CLAWDBOT_GATEWAY_PORT=${CLAWDBOT_GATEWAY_PORT}
+      - 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:
-      - ${PIGBOT_CONFIG_DIR}:/home/node/.pigbot
-      - ${PIGBOT_WORKSPACE_DIR}:/home/node/clawd
+      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.clawdbot
+      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
     ports:
       # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
       # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
-      - "127.0.0.1:${PIGBOT_GATEWAY_PORT}:18789"
+      - "127.0.0.1:${CLAWDBOT_GATEWAY_PORT}:18789"
 
       # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
       # If you expose this publicly, read /gateway/security and firewall accordingly.
@@ -186,9 +186,9 @@ services:
         "dist/index.js",
         "gateway",
         "--bind",
-        "${PIGBOT_GATEWAY_BIND}",
+        "${CLAWDBOT_GATEWAY_BIND}",
         "--port",
-        "${PIGBOT_GATEWAY_PORT}"
+        "${CLAWDBOT_GATEWAY_PORT}"
       ]
 ```
 
@@ -259,15 +259,15 @@ CMD ["node","dist/index.js"]
 
 ```bash
 docker compose build
-docker compose up -d pigbot-gateway
+docker compose up -d moltbot-gateway
 ```
 
 Verify binaries:
 
 ```bash
-docker compose exec pigbot-gateway which gog
-docker compose exec pigbot-gateway which goplaces
-docker compose exec pigbot-gateway which wacli
+docker compose exec moltbot-gateway which gog
+docker compose exec moltbot-gateway which goplaces
+docker compose exec moltbot-gateway which wacli
 ```
 
 Expected output:
@@ -283,7 +283,7 @@ Expected output:
 ## 9) Verify Gateway
 
 ```bash
-docker compose logs -f pigbot-gateway
+docker compose logs -f moltbot-gateway
 ```
 
 Success:
@@ -308,17 +308,17 @@ Paste your gateway token.
 
 ## What persists where (source of truth)
 
-Pigbot runs in Docker, but Docker is not the source of truth.
+Moltbot 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/.pigbot/` | Host volume mount | Includes `pigbot.json`, tokens |
-| Model auth profiles | `/home/node/.pigbot/` | Host volume mount | OAuth tokens, API keys |
-| Skill configs | `/home/node/.pigbot/skills/` | Host volume mount | Skill-level state |
+| Gateway config | `/home/node/.clawdbot/` | Host volume mount | Includes `moltbot.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/.pigbot/` | Host volume mount | Preserves QR login |
-| Gmail keyring | `/home/node/.pigbot/` | Host volume + password | Requires `GOG_KEYRING_PASSWORD` |
+| 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 |