@quantumclaw/quantumclaw 2026.3.22

package/docs/install/gcp.md

@@ -0,0 +1,402 @@
+---
+summary: "Run QuantumClaw Gateway 24/7 on a GCP Compute Engine VM (Docker) with durable state"
+read_when:
+  - You want QuantumClaw 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
+title: "GCP"
+---
+
+# QuantumClaw on GCP Compute Engine (Docker, Production VPS Guide)
+
+## Goal
+
+Run a persistent QuantumClaw Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior.
+
+If you want "QuantumClaw 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 QuantumClaw Gateway in Docker
+- Persist `~/.quantumclaw` + `~/.quantumclaw/workspace` 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 QuantumClaw 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
+
+---
+
+<Steps>
+  <Step title="Install gcloud CLI (or use Console)">
+    **Option A: gcloud CLI** (recommended for automation)
+
+    Install from [https://cloud.google.com/sdk/docs/install](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](https://console.cloud.google.com)
+
+  </Step>
+
+  <Step title="Create a GCP project">
+    **CLI:**
+
+    ```bash
+    gcloud projects create my-quantumclaw-project --name="QuantumClaw Gateway"
+    gcloud config set project my-quantumclaw-project
+    ```
+
+    Enable billing at [https://console.cloud.google.com/billing](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
+
+  </Step>
+
+  <Step title="Create the VM">
+    **Machine types:**
+
+    | Type      | Specs                    | Cost               | Notes                                        |
+    | --------- | ------------------------ | ------------------ | -------------------------------------------- |
+    | e2-medium | 2 vCPU, 4GB RAM          | ~$25/mo            | Most reliable for local Docker builds        |
+    | e2-small  | 2 vCPU, 2GB RAM          | ~$12/mo            | Minimum recommended for Docker build         |
+    | e2-micro  | 2 vCPU (shared), 1GB RAM | Free tier eligible | Often fails with Docker build OOM (exit 137) |
+
+    **CLI:**
+
+    ```bash
+    gcloud compute instances create quantumclaw-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: `quantumclaw-gateway`
+    3. Region: `us-central1`, Zone: `us-central1-a`
+    4. Machine type: `e2-small`
+    5. Boot disk: Debian 12, 20GB
+    6. Create
+
+  </Step>
+
+  <Step title="SSH into the VM">
+    **CLI:**
+
+    ```bash
+    gcloud compute ssh quantumclaw-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.
+
+  </Step>
+
+  <Step title="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 quantumclaw-gateway --zone=us-central1-a
+    ```
+
+    Verify:
+
+    ```bash
+    docker --version
+    docker compose version
+    ```
+
+  </Step>
+
+  <Step title="Clone the QuantumClaw repository">
+    ```bash
+    git clone https://github.com/quantumclaw/quantumclaw.git
+    cd quantumclaw
+    ```
+
+    This guide assumes you will build a custom image to guarantee binary persistence.
+
+  </Step>
+
+  <Step title="Create persistent host directories">
+    Docker containers are ephemeral.
+    All long-lived state must live on the host.
+
+    ```bash
+    mkdir -p ~/.quantumclaw
+    mkdir -p ~/.quantumclaw/workspace
+    ```
+
+  </Step>
+
+  <Step title="Configure environment variables">
+    Create `.env` in the repository root.
+
+    ```bash
+    QUANTUMCLAW_IMAGE=quantumclaw:latest
+    QUANTUMCLAW_GATEWAY_TOKEN=change-me-now
+    QUANTUMCLAW_GATEWAY_BIND=lan
+    QUANTUMCLAW_GATEWAY_PORT=18789
+
+    QUANTUMCLAW_CONFIG_DIR=/home/$USER/.quantumclaw
+    QUANTUMCLAW_WORKSPACE_DIR=/home/$USER/.quantumclaw/workspace
+
+    GOG_KEYRING_PASSWORD=change-me-now
+    XDG_CONFIG_HOME=/home/node/.quantumclaw
+    ```
+
+    Generate strong secrets:
+
+    ```bash
+    openssl rand -hex 32
+    ```
+
+    **Do not commit this file.**
+
+  </Step>
+
+  <Step title="Docker Compose configuration">
+    Create or update `docker-compose.yml`.
+
+    ```yaml
+    services:
+      quantumclaw-gateway:
+        image: ${QUANTUMCLAW_IMAGE}
+        build: .
+        restart: unless-stopped
+        env_file:
+          - .env
+        environment:
+          - HOME=/home/node
+          - NODE_ENV=production
+          - TERM=xterm-256color
+          - QUANTUMCLAW_GATEWAY_BIND=${QUANTUMCLAW_GATEWAY_BIND}
+          - QUANTUMCLAW_GATEWAY_PORT=${QUANTUMCLAW_GATEWAY_PORT}
+          - QUANTUMCLAW_GATEWAY_TOKEN=${QUANTUMCLAW_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:
+          - ${QUANTUMCLAW_CONFIG_DIR}:/home/node/.quantumclaw
+          - ${QUANTUMCLAW_WORKSPACE_DIR}:/home/node/.quantumclaw/workspace
+        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:${QUANTUMCLAW_GATEWAY_PORT}:18789"
+        command:
+          [
+            "node",
+            "dist/index.js",
+            "gateway",
+            "--bind",
+            "${QUANTUMCLAW_GATEWAY_BIND}",
+            "--port",
+            "${QUANTUMCLAW_GATEWAY_PORT}",
+            "--allow-unconfigured",
+          ]
+    ```
+
+    `--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.
+
+  </Step>
+
+  <Step title="Shared Docker VM runtime steps">
+    Use the shared runtime guide for the common Docker host flow:
+
+    - [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
+    - [Build and launch](/install/docker-vm-runtime#build-and-launch)
+    - [What persists where](/install/docker-vm-runtime#what-persists-where)
+    - [Updates](/install/docker-vm-runtime#updates)
+
+  </Step>
+
+  <Step title="GCP-specific launch notes">
+    On GCP, if build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory. Use `e2-small` minimum, or `e2-medium` for more reliable first builds.
+
+    When binding to LAN (`QUANTUMCLAW_GATEWAY_BIND=lan`), configure a trusted browser origin before continuing:
+
+    ```bash
+    docker compose run --rm quantumclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
+    ```
+
+    If you changed the gateway port, replace `18789` with your configured port.
+
+  </Step>
+
+  <Step title="Access from your laptop">
+    Create an SSH tunnel to forward the Gateway port:
+
+    ```bash
+    gcloud compute ssh quantumclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
+    ```
+
+    Open in your browser:
+
+    `http://127.0.0.1:18789/`
+
+    Fetch a fresh tokenized dashboard link:
+
+    ```bash
+    docker compose run --rm quantumclaw-cli dashboard --no-open
+    ```
+
+    Paste the token from that URL.
+
+    If Control UI shows `unauthorized` or `disconnected (1008): pairing required`, approve the browser device:
+
+    ```bash
+    docker compose run --rm quantumclaw-cli devices list
+    docker compose run --rm quantumclaw-cli devices approve <requestId>
+    ```
+
+    Need the shared persistence and update reference again?
+    See [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where) and [Docker VM Runtime updates](/install/docker-vm-runtime#updates).
+
+  </Step>
+</Steps>
+
+---
+
+## 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 Docker build fails with `Killed` and `exit code 137`, the VM was OOM-killed. Upgrade to e2-small (minimum) or e2-medium (recommended for reliable local builds):
+
+```bash
+# Stop the VM first
+gcloud compute instances stop quantumclaw-gateway --zone=us-central1-a
+
+# Change machine type
+gcloud compute instances set-machine-type quantumclaw-gateway \
+  --zone=us-central1-a \
+  --machine-type=e2-small
+
+# Start the VM
+gcloud compute instances start quantumclaw-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 quantumclaw-deploy \
+     --display-name="QuantumClaw Deployment"
+   ```
+
+2. Grant Compute Instance Admin role (or narrower custom role):
+
+   ```bash
+   gcloud projects add-iam-policy-binding my-quantumclaw-project \
+     --member="serviceAccount:quantumclaw-deploy@my-quantumclaw-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](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/install/hetzner.md

@@ -0,0 +1,251 @@
+---
+summary: "Run QuantumClaw Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
+read_when:
+  - You want QuantumClaw 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 QuantumClaw in Docker on Hetzner or a similar provider
+title: "Hetzner"
+---
+
+# QuantumClaw on Hetzner (Docker, Production VPS Guide)
+
+## Goal
+
+Run a persistent QuantumClaw Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
+
+If you want “QuantumClaw 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.
+
+Security model reminder:
+
+- Company-shared agents are fine when everyone is in the same trust boundary and the runtime is business-only.
+- Keep strict separation: dedicated VPS/runtime + dedicated accounts; no personal Apple/Google/browser/password-manager profiles on that host.
+- If users are adversarial to each other, split by gateway/host/OS user.
+
+See [Security](/gateway/security) and [VPS hosting](/vps).
+
+## What are we doing (simple terms)?
+
+- Rent a small Linux server (Hetzner VPS)
+- Install Docker (isolated app runtime)
+- Start the QuantumClaw Gateway in Docker
+- Persist `~/.quantumclaw` + `~/.quantumclaw/workspace` 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 assumes Ubuntu or Debian on Hetzner.  
+If you are on another Linux VPS, map packages accordingly.
+For the generic Docker flow, see [Docker](/install/docker).
+
+---
+
+## Quick path (experienced operators)
+
+1. Provision Hetzner VPS
+2. Install Docker
+3. Clone QuantumClaw 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
+- Basic comfort with SSH + copy/paste
+- ~20 minutes
+- Docker and Docker Compose
+- Model auth credentials
+- Optional provider credentials
+  - WhatsApp QR
+  - Telegram bot token
+  - Gmail OAuth
+
+---
+
+<Steps>
+  <Step title="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.
+
+  </Step>
+
+  <Step title="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
+    ```
+
+  </Step>
+
+  <Step title="Clone the QuantumClaw repository">
+    ```bash
+    git clone https://github.com/quantumclaw/quantumclaw.git
+    cd quantumclaw
+    ```
+
+    This guide assumes you will build a custom image to guarantee binary persistence.
+
+  </Step>
+
+  <Step title="Create persistent host directories">
+    Docker containers are ephemeral.
+    All long-lived state must live on the host.
+
+    ```bash
+    mkdir -p /root/.quantumclaw/workspace
+
+    # Set ownership to the container user (uid 1000):
+    chown -R 1000:1000 /root/.quantumclaw
+    ```
+
+  </Step>
+
+  <Step title="Configure environment variables">
+    Create `.env` in the repository root.
+
+    ```bash
+    QUANTUMCLAW_IMAGE=quantumclaw:latest
+    QUANTUMCLAW_GATEWAY_TOKEN=change-me-now
+    QUANTUMCLAW_GATEWAY_BIND=lan
+    QUANTUMCLAW_GATEWAY_PORT=18789
+
+    QUANTUMCLAW_CONFIG_DIR=/root/.quantumclaw
+    QUANTUMCLAW_WORKSPACE_DIR=/root/.quantumclaw/workspace
+
+    GOG_KEYRING_PASSWORD=change-me-now
+    XDG_CONFIG_HOME=/home/node/.quantumclaw
+    ```
+
+    Generate strong secrets:
+
+    ```bash
+    openssl rand -hex 32
+    ```
+
+    **Do not commit this file.**
+
+  </Step>
+
+  <Step title="Docker Compose configuration">
+    Create or update `docker-compose.yml`.
+
+    ```yaml
+    services:
+      quantumclaw-gateway:
+        image: ${QUANTUMCLAW_IMAGE}
+        build: .
+        restart: unless-stopped
+        env_file:
+          - .env
+        environment:
+          - HOME=/home/node
+          - NODE_ENV=production
+          - TERM=xterm-256color
+          - QUANTUMCLAW_GATEWAY_BIND=${QUANTUMCLAW_GATEWAY_BIND}
+          - QUANTUMCLAW_GATEWAY_PORT=${QUANTUMCLAW_GATEWAY_PORT}
+          - QUANTUMCLAW_GATEWAY_TOKEN=${QUANTUMCLAW_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:
+          - ${QUANTUMCLAW_CONFIG_DIR}:/home/node/.quantumclaw
+          - ${QUANTUMCLAW_WORKSPACE_DIR}:/home/node/.quantumclaw/workspace
+        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:${QUANTUMCLAW_GATEWAY_PORT}:18789"
+        command:
+          [
+            "node",
+            "dist/index.js",
+            "gateway",
+            "--bind",
+            "${QUANTUMCLAW_GATEWAY_BIND}",
+            "--port",
+            "${QUANTUMCLAW_GATEWAY_PORT}",
+            "--allow-unconfigured",
+          ]
+    ```
+
+    `--allow-unconfigured` is only for bootstrap convenience, it is not a replacement for a proper gateway configuration. Still set auth (`gateway.auth.token` or password) and use safe bind settings for your deployment.
+
+  </Step>
+
+  <Step title="Shared Docker VM runtime steps">
+    Use the shared runtime guide for the common Docker host flow:
+
+    - [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
+    - [Build and launch](/install/docker-vm-runtime#build-and-launch)
+    - [What persists where](/install/docker-vm-runtime#what-persists-where)
+    - [Updates](/install/docker-vm-runtime#updates)
+
+  </Step>
+
+  <Step title="Hetzner-specific access">
+    After the shared build and launch steps, tunnel 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.
+
+  </Step>
+</Steps>
+
+The shared persistence map lives in [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where).
+
+## Infrastructure as Code (Terraform)
+
+For teams preferring infrastructure-as-code workflows, a community-maintained Terraform setup provides:
+
+- Modular Terraform configuration with remote state management
+- Automated provisioning via cloud-init
+- Deployment scripts (bootstrap, deploy, backup/restore)
+- Security hardening (firewall, UFW, SSH-only access)
+- SSH tunnel configuration for gateway access
+
+**Repositories:**
+
+- Infrastructure: [quantumclaw-terraform-hetzner](https://github.com/andreesg/quantumclaw-terraform-hetzner)
+- Docker config: [quantumclaw-docker-config](https://github.com/andreesg/quantumclaw-docker-config)
+
+This approach complements the Docker setup above with reproducible deployments, version-controlled infrastructure, and automated disaster recovery.
+
+> **Note:** Community-maintained. For issues or contributions, see the repository links above.
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep QuantumClaw up to date: [Updating](/install/updating)