@gguf/pigbot 0.0.1 → 0.0.3

package/docs/platforms/digitalocean.md

@@ -0,0 +1,243 @@
+---
+summary: "Moltbot on DigitalOcean (simple paid VPS option)"
+read_when:
+  - Setting up Moltbot on DigitalOcean
+  - Looking for cheap VPS hosting for Moltbot
+---
+
+# Moltbot on DigitalOcean
+
+## Goal
+
+Run a persistent Moltbot Gateway on DigitalOcean for **$6/month** (or $4/mo with reserved pricing).
+
+If you want a $0/month option and don’t mind ARM + provider-specific setup, see the [Oracle Cloud guide](/platforms/oracle).
+
+## Cost Comparison (2026)
+
+| Provider | Plan | Specs | Price/mo | Notes |
+|----------|------|-------|----------|-------|
+| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0 | ARM, limited capacity / signup quirks |
+| Hetzner | CX22 | 2 vCPU, 4GB RAM | €3.79 (~$4) | Cheapest paid option |
+| DigitalOcean | Basic | 1 vCPU, 1GB RAM | $6 | Easy UI, good docs |
+| Vultr | Cloud Compute | 1 vCPU, 1GB RAM | $6 | Many locations |
+| Linode | Nanode | 1 vCPU, 1GB RAM | $5 | Now part of Akamai |
+
+**Picking a provider:**
+- DigitalOcean: simplest UX + predictable setup (this guide)
+- Hetzner: good price/perf (see [Hetzner guide](/platforms/hetzner))
+- Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle))
+
+---
+
+## Prerequisites
+
+- DigitalOcean account ([signup with $200 free credit](https://m.do.co/c/signup))
+- SSH key pair (or willingness to use password auth)
+- ~20 minutes
+
+## 1) Create a Droplet
+
+1. Log into [DigitalOcean](https://cloud.digitalocean.com/)
+2. Click **Create → Droplets**
+3. Choose:
+   - **Region:** Closest to you (or your users)
+   - **Image:** Ubuntu 24.04 LTS
+   - **Size:** Basic → Regular → **$6/mo** (1 vCPU, 1GB RAM, 25GB SSD)
+   - **Authentication:** SSH key (recommended) or password
+4. Click **Create Droplet**
+5. Note the IP address
+
+## 2) Connect via SSH
+
+```bash
+ssh root@YOUR_DROPLET_IP
+```
+
+## 3) Install Moltbot
+
+```bash
+# Update system
+apt update && apt upgrade -y
+
+# Install Node.js 22
+curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+apt install -y nodejs
+
+# Install Moltbot
+curl -fsSL https://molt.bot/install.sh | bash
+
+# Verify
+moltbot --version
+```
+
+## 4) Run Onboarding
+
+```bash
+moltbot onboard --install-daemon
+```
+
+The wizard will walk you through:
+- Model auth (API keys or OAuth)
+- Channel setup (Telegram, WhatsApp, Discord, etc.)
+- Gateway token (auto-generated)
+- Daemon installation (systemd)
+
+## 5) Verify the Gateway
+
+```bash
+# Check status
+moltbot status
+
+# Check service
+systemctl --user status moltbot-gateway.service
+
+# View logs
+journalctl --user -u moltbot-gateway.service -f
+```
+
+## 6) Access the Dashboard
+
+The gateway binds to loopback by default. To access the Control UI:
+
+**Option A: SSH Tunnel (recommended)**
+```bash
+# From your local machine
+ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
+
+# Then open: http://localhost:18789
+```
+
+**Option B: Tailscale Serve (HTTPS, loopback-only)**
+```bash
+# On the droplet
+curl -fsSL https://tailscale.com/install.sh | sh
+tailscale up
+
+# Configure Gateway to use Tailscale Serve
+moltbot config set gateway.tailscale.mode serve
+moltbot gateway restart
+```
+
+Open: `https://<magicdns>/`
+
+Notes:
+- Serve keeps the Gateway loopback-only and authenticates via Tailscale identity headers.
+- To require token/password instead, set `gateway.auth.allowTailscale: false` or use `gateway.auth.mode: "password"`.
+
+**Option C: Tailnet bind (no Serve)**
+```bash
+moltbot config set gateway.bind tailnet
+moltbot gateway restart
+```
+
+Open: `http://<tailscale-ip>:18789` (token required).
+
+## 7) Connect Your Channels
+
+### Telegram
+```bash
+moltbot pairing list telegram
+moltbot pairing approve telegram <CODE>
+```
+
+### WhatsApp
+```bash
+moltbot channels login whatsapp
+# Scan QR code
+```
+
+See [Channels](/channels) for other providers.
+
+---
+
+## Optimizations for 1GB RAM
+
+The $6 droplet only has 1GB RAM. To keep things running smoothly:
+
+### Add swap (recommended)
+```bash
+fallocate -l 2G /swapfile
+chmod 600 /swapfile
+mkswap /swapfile
+swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+```
+
+### Use a lighter model
+If you're hitting OOMs, consider:
+- Using API-based models (Claude, GPT) instead of local models
+- Setting `agents.defaults.model.primary` to a smaller model
+
+### Monitor memory
+```bash
+free -h
+htop
+```
+
+---
+
+## Persistence
+
+All state lives in:
+- `~/.clawdbot/` — config, credentials, session data
+- `~/clawd/` — workspace (SOUL.md, memory, etc.)
+
+These survive reboots. Back them up periodically:
+```bash
+tar -czvf moltbot-backup.tar.gz ~/.clawdbot ~/clawd
+```
+
+---
+
+## Oracle Cloud Free Alternative
+
+Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful than any paid option here — for $0/month.
+
+| What you get | Specs |
+|--------------|-------|
+| **4 OCPUs** | ARM Ampere A1 |
+| **24GB RAM** | More than enough |
+| **200GB storage** | Block volume |
+| **Forever free** | No credit card charges |
+
+**Caveats:**
+- Signup can be finicky (retry if it fails)
+- ARM architecture — most things work, but some binaries need ARM builds
+
+For the full setup guide, see [Oracle Cloud](/platforms/oracle). For signup tips and troubleshooting the enrollment process, see this [community guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd).
+
+---
+
+## Troubleshooting
+
+### Gateway won't start
+```bash
+moltbot gateway status
+moltbot doctor --non-interactive
+journalctl -u moltbot --no-pager -n 50
+```
+
+### Port already in use
+```bash
+lsof -i :18789
+kill <PID>
+```
+
+### Out of memory
+```bash
+# Check memory
+free -h
+
+# Add more swap
+# Or upgrade to $12/mo droplet (2GB RAM)
+```
+
+---
+
+## See Also
+
+- [Hetzner guide](/platforms/hetzner) — cheaper, more powerful
+- [Docker install](/install/docker) — containerized setup
+- [Tailscale](/gateway/tailscale) — secure remote access
+- [Configuration](/gateway/configuration) — full config reference

package/docs/platforms/exe-dev.md

@@ -1,5 +1,5 @@
 ---
-summary: "Run Pigbot Gateway on exe.dev (VM + HTTPS proxy) for remote access"
+summary: "Run Moltbot Gateway on exe.dev (VM + HTTPS proxy) for remote access"
 read_when:
   - You want a cheap always-on Linux host for the Gateway
   - You want remote Control UI access without running your own VPS
@@ -7,7 +7,7 @@ read_when:
 
 # exe.dev
 
-Goal: Pigbot Gateway running on an exe.dev VM, reachable from your laptop via:
+Goal: Moltbot Gateway running on an exe.dev VM, reachable from your laptop via:
 - **exe.dev HTTPS proxy** (easy, no tunnel) or
 - **SSH tunnel** (most secure; loopback-only Gateway)
 
@@ -17,8 +17,8 @@ If you’re on any other Linux VPS, the same steps apply — you just won’t us
 
 ## Beginner quick path
 
-1) Create VM → install Node 22 → install Pigbot  
-2) Run `pigbot onboard --install-daemon`  
+1) Create VM → install Node 22 → install Moltbot  
+2) Run `moltbot onboard --install-daemon`  
 3) Tunnel from laptop (`ssh -N -L 18789:127.0.0.1:18789 …`)  
 4) Open `http://127.0.0.1:18789/` and paste your token
 
@@ -34,16 +34,16 @@ If you’re on any other Linux VPS, the same steps apply — you just won’t us
 From your laptop:
 
 ```bash
-ssh exe.dev new --name=pigbot
+ssh exe.dev new --name=moltbot
 ```
 
 Then connect:
 
 ```bash
-ssh pigbot.exe.xyz
+ssh moltbot.exe.xyz
 ```
 
-Tip: keep this VM **stateful**. Pigbot stores state under `~/.pigbot/` and `~/clawd/`.
+Tip: keep this VM **stateful**. Moltbot stores state under `~/.clawdbot/` and `~/clawd/`.
 
 ## 2) Install prerequisites (on the VM)
 
@@ -69,13 +69,13 @@ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
 sudo apt-get install -y nodejs
 ```
 
-## 3) Install Pigbot
+## 3) Install Moltbot
 
 Recommended on servers: npm global install.
 
 ```bash
-npm i -g pigbot@latest
-pigbot --version
+npm i -g moltbot@latest
+moltbot --version
 ```
 
 If native deps fail to install (rare; usually `sharp`), add build tools:
@@ -89,12 +89,12 @@ sudo apt-get install -y build-essential python3
 Run the onboarding wizard on the VM:
 
 ```bash
-pigbot onboard --install-daemon
+moltbot onboard --install-daemon
 ```
 
 It can set up:
 - `~/clawd` workspace bootstrap
-- `~/.pigbot/pigbot.json` config
+- `~/.clawdbot/moltbot.json` config
 - model auth profiles
 - model provider config/login
 - Linux systemd **user** service (service)
@@ -108,7 +108,7 @@ If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, th
 Keep Gateway on loopback (default) and tunnel it from your laptop:
 
 ```bash
-ssh -N -L 18789:127.0.0.1:18789 pigbot.exe.xyz
+ssh -N -L 18789:127.0.0.1:18789 moltbot.exe.xyz
 ```
 
 Open locally:
@@ -121,11 +121,11 @@ Runbook: [Remote access](/gateway/remote)
 To let exe.dev proxy traffic to the VM, bind the Gateway to the LAN interface and set a token:
 
 ```bash
-export PIGBOT_GATEWAY_TOKEN="$(openssl rand -hex 32)"
-pigbot gateway --bind lan --port 8080 --token "$PIGBOT_GATEWAY_TOKEN"
+export CLAWDBOT_GATEWAY_TOKEN="$(openssl rand -hex 32)"
+moltbot gateway --bind lan --port 8080 --token "$CLAWDBOT_GATEWAY_TOKEN"
 ```
 
-For service runs, persist it in `~/.pigbot/pigbot.json`:
+For service runs, persist it in `~/.clawdbot/moltbot.json`:
 
 ```json5
 {
@@ -139,17 +139,17 @@ For service runs, persist it in `~/.pigbot/pigbot.json`:
 ```
 
 Notes:
-- Non-loopback binds require `gateway.auth.token` (or `PIGBOT_GATEWAY_TOKEN`).
+- Non-loopback binds require `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`).
 - `gateway.remote.token` is only for remote CLI calls; it does not enable local auth.
 
 Then point exe.dev’s proxy at `8080` (or whatever port you chose) and open your VM’s HTTPS URL:
 
 ```bash
-ssh exe.dev share port pigbot 8080
+ssh exe.dev share port moltbot 8080
 ```
 
 Open:
-- `https://pigbot.exe.xyz/`
+- `https://moltbot.exe.xyz/`
 
 In the Control UI, paste the token (UI → Settings → token). The UI sends it as `connect.params.auth.token`.
 
@@ -161,10 +161,10 @@ Control UI details: [Control UI](/web/control-ui)
 
 ## 6) Keep it running (service)
 
-On Linux, Pigbot uses a systemd **user** service. After `--install-daemon`, verify:
+On Linux, Moltbot uses a systemd **user** service. After `--install-daemon`, verify:
 
 ```bash
-systemctl --user status pigbot-gateway[-<profile>].service
+systemctl --user status moltbot-gateway[-<profile>].service
 ```
 
 If the service dies after logout, enable lingering:
@@ -178,10 +178,10 @@ More: [Linux](/platforms/linux)
 ## 7) Updates
 
 ```bash
-npm i -g pigbot@latest
-pigbot doctor
-pigbot gateway restart
-pigbot health
+npm i -g moltbot@latest
+moltbot doctor
+moltbot gateway restart
+moltbot health
 ```
 
 Guide: [Updating](/install/updating)

package/docs/platforms/fly.md

@@ -1,11 +1,11 @@
 ---
 title: Fly.io
-description: Deploy Pigbot on Fly.io
+description: Deploy Moltbot on Fly.io
 ---
 
 # Fly.io Deployment
 
-**Goal:** Pigbot Gateway running on a [Fly.io](https://fly.io) machine with persistent storage, automatic HTTPS, and Discord/channel access.
+**Goal:** Moltbot Gateway running on a [Fly.io](https://fly.io) machine with persistent storage, automatic HTTPS, and Discord/channel access.
 
 ## What you need
 
@@ -25,24 +25,26 @@ description: Deploy Pigbot on Fly.io
 
 ```bash
 # Clone the repo
-git clone https://github.com/pigbot/pigbot.git
-cd pigbot
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
 
 # Create a new Fly app (pick your own name)
-fly apps create my-pigbot
+fly apps create my-moltbot
 
 # Create a persistent volume (1GB is usually enough)
-fly volumes create pigbot_data --size 1 --region iad
+fly volumes create moltbot_data --size 1 --region iad
 ```
 
 **Tip:** Choose a region close to you. Common options: `lhr` (London), `iad` (Virginia), `sjc` (San Jose).
 
 ## 2) Configure fly.toml
 
-Edit `fly.toml` to match your app name and requirements:
+Edit `fly.toml` to match your app name and requirements.
+
+**Security note:** The default config exposes a public URL. For a hardened deployment with no public IP, see [Private Deployment](#private-deployment-hardened) or use `fly.private.toml`.
 
 ```toml
-app = "my-pigbot"  # Your app name
+app = "my-moltbot"  # Your app name
 primary_region = "iad"
 
 [build]
@@ -50,8 +52,8 @@ primary_region = "iad"
 
 [env]
   NODE_ENV = "production"
-  PIGBOT_PREFER_PNPM = "1"
-  PIGBOT_STATE_DIR = "/data"
+  CLAWDBOT_PREFER_PNPM = "1"
+  CLAWDBOT_STATE_DIR = "/data"
   NODE_OPTIONS = "--max-old-space-size=1536"
 
 [processes]
@@ -70,7 +72,7 @@ primary_region = "iad"
   memory = "2048mb"
 
 [mounts]
-  source = "pigbot_data"
+  source = "moltbot_data"
   destination = "/data"
 ```
 
@@ -80,14 +82,15 @@ primary_region = "iad"
 |---------|-----|
 | `--bind lan` | Binds to `0.0.0.0` so Fly's proxy can reach the gateway |
 | `--allow-unconfigured` | Starts without a config file (you'll create one after) |
+| `internal_port = 3000` | Must match `--port 3000` (or `CLAWDBOT_GATEWAY_PORT`) for Fly health checks |
 | `memory = "2048mb"` | 512MB is too small; 2GB recommended |
-| `PIGBOT_STATE_DIR = "/data"` | Persists state on the volume |
+| `CLAWDBOT_STATE_DIR = "/data"` | Persists state on the volume |
 
 ## 3) Set secrets
 
 ```bash
 # Required: Gateway token (for non-loopback binding)
-fly secrets set PIGBOT_GATEWAY_TOKEN=$(openssl rand -hex 32)
+fly secrets set CLAWDBOT_GATEWAY_TOKEN=$(openssl rand -hex 32)
 
 # Model provider API keys
 fly secrets set ANTHROPIC_API_KEY=sk-ant-...
@@ -101,8 +104,9 @@ fly secrets set DISCORD_BOT_TOKEN=MTQ...
 ```
 
 **Notes:**
-- Non-loopback binds (`--bind lan`) require `PIGBOT_GATEWAY_TOKEN` for security.
+- Non-loopback binds (`--bind lan`) require `CLAWDBOT_GATEWAY_TOKEN` for security.
 - Treat these tokens like passwords.
+- **Prefer env vars over config file** for all API keys and tokens. This keeps secrets out of `moltbot.json` where they could be accidentally exposed or logged.
 
 ## 4) Deploy
 
@@ -135,7 +139,7 @@ fly ssh console
 Create the config directory and file:
 ```bash
 mkdir -p /data
-cat > /data/pigbot.json << 'EOF'
+cat > /data/moltbot.json << 'EOF'
 {
   "agents": {
     "defaults": {
@@ -181,13 +185,13 @@ cat > /data/pigbot.json << 'EOF'
     "bind": "auto"
   },
   "meta": {
-    "lastTouchedVersion": "2026.1.24"
+    "lastTouchedVersion": "2026.1.26"
   }
 }
 EOF
 ```
 
-**Note:** With `PIGBOT_STATE_DIR=/data`, the config path is `/data/pigbot.json`.
+**Note:** With `CLAWDBOT_STATE_DIR=/data`, the config path is `/data/moltbot.json`.
 
 **Note:** The Discord token can come from either:
 - Environment variable: `DISCORD_BOT_TOKEN` (recommended for secrets)
@@ -210,9 +214,9 @@ Open in browser:
 fly open
 ```
 
-Or visit `https://my-pigbot.fly.dev/`
+Or visit `https://my-moltbot.fly.dev/`
 
-Paste your gateway token (the one from `PIGBOT_GATEWAY_TOKEN`) to authenticate.
+Paste your gateway token (the one from `CLAWDBOT_GATEWAY_TOKEN`) to authenticate.
 
 ### Logs
 
@@ -235,6 +239,12 @@ The gateway is binding to `127.0.0.1` instead of `0.0.0.0`.
 
 **Fix:** Add `--bind lan` to your process command in `fly.toml`.
 
+### Health checks failing / connection refused
+
+Fly can't reach the gateway on the configured port.
+
+**Fix:** Ensure `internal_port` matches the gateway port (set `--port 3000` or `CLAWDBOT_GATEWAY_PORT=3000`).
+
 ### OOM / Memory Issues
 
 Container keeps restarting or getting killed. Signs: `SIGABRT`, `v8::internal::Runtime_AllocateInYoungGeneration`, or silent restarts.
@@ -268,11 +278,11 @@ The lock file is at `/data/gateway.*.lock` (not in a subdirectory).
 
 ### Config Not Being Read
 
-If using `--allow-unconfigured`, the gateway creates a minimal config. Your custom config at `/data/.pigbot/pigbot.json` should be read on restart.
+If using `--allow-unconfigured`, the gateway creates a minimal config. Your custom config at `/data/moltbot.json` should be read on restart.
 
 Verify the config exists:
 ```bash
-fly ssh console --command "cat /data/.pigbot/pigbot.json"
+fly ssh console --command "cat /data/moltbot.json"
 ```
 
 ### Writing Config via SSH
@@ -281,18 +291,24 @@ The `fly ssh console -C` command doesn't support shell redirection. To write a c
 
 ```bash
 # Use echo + tee (pipe from local to remote)
-echo '{"your":"config"}' | fly ssh console -C "tee /data/.pigbot/pigbot.json"
+echo '{"your":"config"}' | fly ssh console -C "tee /data/moltbot.json"
 
 # Or use sftp
 fly sftp shell
-> put /local/path/config.json /data/.pigbot/pigbot.json
+> put /local/path/config.json /data/moltbot.json
 ```
 
 **Note:** `fly sftp` may fail if the file already exists. Delete first:
 ```bash
-fly ssh console --command "rm /data/.pigbot/pigbot.json"
+fly ssh console --command "rm /data/moltbot.json"
 ```
 
+### State Not Persisting
+
+If you lose credentials or sessions after a restart, the state dir is writing to the container filesystem.
+
+**Fix:** Ensure `CLAWDBOT_STATE_DIR=/data` is set in `fly.toml` and redeploy.
+
 ## Updates
 
 ```bash
@@ -324,12 +340,121 @@ fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js g
 
 **Note:** After `fly deploy`, the machine command may reset to what's in `fly.toml`. If you made manual changes, re-apply them after deploy.
 
+## Private Deployment (Hardened)
+
+By default, Fly allocates public IPs, making your gateway accessible at `https://your-app.fly.dev`. This is convenient but means your deployment is discoverable by internet scanners (Shodan, Censys, etc.).
+
+For a hardened deployment with **no public exposure**, use the private template.
+
+### When to use private deployment
+
+- You only make **outbound** calls/messages (no inbound webhooks)
+- You use **ngrok or Tailscale** tunnels for any webhook callbacks
+- You access the gateway via **SSH, proxy, or WireGuard** instead of browser
+- You want the deployment **hidden from internet scanners**
+
+### Setup
+
+Use `fly.private.toml` instead of the standard config:
+
+```bash
+# Deploy with private config
+fly deploy -c fly.private.toml
+```
+
+Or convert an existing deployment:
+
+```bash
+# List current IPs
+fly ips list -a my-moltbot
+
+# Release public IPs
+fly ips release <public-ipv4> -a my-moltbot
+fly ips release <public-ipv6> -a my-moltbot
+
+# Switch to private config so future deploys don't re-allocate public IPs
+# (remove [http_service] or deploy with the private template)
+fly deploy -c fly.private.toml
+
+# Allocate private-only IPv6
+fly ips allocate-v6 --private -a my-moltbot
+```
+
+After this, `fly ips list` should show only a `private` type IP:
+```
+VERSION  IP                   TYPE             REGION
+v6       fdaa:x:x:x:x::x      private          global
+```
+
+### Accessing a private deployment
+
+Since there's no public URL, use one of these methods:
+
+**Option 1: Local proxy (simplest)**
+```bash
+# Forward local port 3000 to the app
+fly proxy 3000:3000 -a my-moltbot
+
+# Then open http://localhost:3000 in browser
+```
+
+**Option 2: WireGuard VPN**
+```bash
+# Create WireGuard config (one-time)
+fly wireguard create
+
+# Import to WireGuard client, then access via internal IPv6
+# Example: http://[fdaa:x:x:x:x::x]:3000
+```
+
+**Option 3: SSH only**
+```bash
+fly ssh console -a my-moltbot
+```
+
+### Webhooks with private deployment
+
+If you need webhook callbacks (Twilio, Telnyx, etc.) without public exposure:
+
+1. **ngrok tunnel** - Run ngrok inside the container or as a sidecar
+2. **Tailscale Funnel** - Expose specific paths via Tailscale
+3. **Outbound-only** - Some providers (Twilio) work fine for outbound calls without webhooks
+
+Example voice-call config with ngrok:
+```json
+{
+  "plugins": {
+    "entries": {
+      "voice-call": {
+        "enabled": true,
+        "config": {
+          "provider": "twilio",
+          "tunnel": { "provider": "ngrok" }
+        }
+      }
+    }
+  }
+}
+```
+
+The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself.
+
+### Security benefits
+
+| Aspect | Public | Private |
+|--------|--------|---------|
+| Internet scanners | Discoverable | Hidden |
+| Direct attacks | Possible | Blocked |
+| Control UI access | Browser | Proxy/VPN |
+| Webhook delivery | Direct | Via tunnel |
+
 ## Notes
 
 - Fly.io uses **x86 architecture** (not ARM)
 - The Dockerfile is compatible with both architectures
 - For WhatsApp/Telegram onboarding, use `fly ssh console`
 - Persistent data lives on the volume at `/data`
+- Signal requires Java + signal-cli; use a custom image and keep memory at 2GB+.
 
 ## Cost