fengming 0.3.9 → 0.3.11

package/docs/install/gcp.md

@@ -1,418 +0,0 @@
----
-summary: "Run FengMing Gateway 24/7 on a GCP Compute Engine VM (Docker) with durable state"
-read_when:
-  - You want FengMing 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"
----
-
-Run a persistent FengMing Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior.
-
-If you want "FengMing 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 FengMing Gateway in Docker
-- Persist `~/.fengming` + `~/.fengming/workspace` on the host (survives restarts/rebuilds)
-- Access the Control UI from your laptop via an SSH tunnel
-
-That mounted `~/.fengming` state includes `fengming.json`, per-agent
-`agents/<agentId>/agent/auth-profiles.json`, and `.env`.
-
-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 FengMing 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-fengming-project --name="FengMing Gateway"
-    gcloud config set project my-fengming-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 fengming-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: `fengming-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 fengming-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 fengming-gateway --zone=us-central1-a
-    ```
-
-    Verify:
-
-    ```bash
-    docker --version
-    docker compose version
-    ```
-
-  </Step>
-
-  <Step title="Clone the FengMing repository">
-    ```bash
-    git clone https://github.com/fengming/fengming.git
-    cd fengming
-    ```
-
-    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 ~/.fengming
-    mkdir -p ~/.fengming/workspace
-    ```
-
-  </Step>
-
-  <Step title="Configure environment variables">
-    Create `.env` in the repository root.
-
-    ```bash
-    FENGMING_IMAGE=fengming:latest
-    FENGMING_GATEWAY_TOKEN=
-    FENGMING_GATEWAY_BIND=lan
-    FENGMING_GATEWAY_PORT=18789
-
-    FENGMING_CONFIG_DIR=/home/$USER/.fengming
-    FENGMING_WORKSPACE_DIR=/home/$USER/.fengming/workspace
-
-    GOG_KEYRING_PASSWORD=
-    XDG_CONFIG_HOME=/home/node/.fengming
-    ```
-
-    Set `FENGMING_GATEWAY_TOKEN` when you want to manage the stable gateway
-    token through `.env`; otherwise configure `gateway.auth.token` before
-    relying on clients across restarts. If neither source exists, FengMing uses
-    a runtime-only token for that startup. Generate a keyring password and paste
-    it into `GOG_KEYRING_PASSWORD`:
-
-    ```bash
-    openssl rand -hex 32
-    ```
-
-    **Do not commit this file.**
-
-    This `.env` file is for container/runtime env such as `FENGMING_GATEWAY_TOKEN`.
-    Stored provider OAuth/API-key auth lives in the mounted
-    `~/.fengming/agents/<agentId>/agent/auth-profiles.json`.
-
-  </Step>
-
-  <Step title="Docker Compose configuration">
-    Create or update `docker-compose.yml`.
-
-    ```yaml
-    services:
-      fengming-gateway:
-        image: ${FENGMING_IMAGE}
-        build: .
-        restart: unless-stopped
-        env_file:
-          - .env
-        environment:
-          - HOME=/home/node
-          - NODE_ENV=production
-          - TERM=xterm-256color
-          - FENGMING_GATEWAY_BIND=${FENGMING_GATEWAY_BIND}
-          - FENGMING_GATEWAY_PORT=${FENGMING_GATEWAY_PORT}
-          - FENGMING_GATEWAY_TOKEN=${FENGMING_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:
-          - ${FENGMING_CONFIG_DIR}:/home/node/.fengming
-          - ${FENGMING_WORKSPACE_DIR}:/home/node/.fengming/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:${FENGMING_GATEWAY_PORT}:18789"
-        command:
-          [
-            "node",
-            "dist/index.js",
-            "gateway",
-            "--bind",
-            "${FENGMING_GATEWAY_BIND}",
-            "--port",
-            "${FENGMING_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 (`FENGMING_GATEWAY_BIND=lan`), configure a trusted browser origin before continuing:
-
-    ```bash
-    docker compose run --rm fengming-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 fengming-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
-    ```
-
-    Open in your browser:
-
-    `http://127.0.0.1:18789/`
-
-    Reprint a clean dashboard link:
-
-    ```bash
-    docker compose run --rm fengming-cli dashboard --no-open
-    ```
-
-    If the UI prompts for shared-secret auth, paste the configured token or
-    password into Control UI settings. This Docker flow writes a token by
-    default; if you switch the container config to password auth, use that
-    password instead.
-
-    If Control UI shows `unauthorized` or `disconnected (1008): pairing required`, approve the browser device:
-
-    ```bash
-    docker compose run --rm fengming-cli devices list
-    docker compose run --rm fengming-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 fengming-gateway --zone=us-central1-a
-
-# Change machine type
-gcloud compute instances set-machine-type fengming-gateway \
-  --zone=us-central1-a \
-  --machine-type=e2-small
-
-# Start the VM
-gcloud compute instances start fengming-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 fengming-deploy \
-     --display-name="FengMing Deployment"
-   ```
-
-2. Grant Compute Instance Admin role (or narrower custom role):
-
-   ```bash
-   gcloud projects add-iam-policy-binding my-fengming-project \
-     --member="serviceAccount:fengming-deploy@my-fengming-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)
-
-## Related
-
-- [Install overview](/install)
-- [Azure](/install/azure)
-- [VPS hosting](/vps)

package/docs/install/hetzner.md

@@ -1,285 +0,0 @@
----
-summary: "Run FengMing Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
-read_when:
-  - You want FengMing 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 FengMing in Docker on Hetzner or a similar provider
-title: "Hetzner"
----
-
-## Goal
-
-Run a persistent FengMing Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
-
-If you want "FengMing 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 FengMing Gateway in Docker
-- Persist `~/.fengming` + `~/.fengming/workspace` on the host (survives restarts/rebuilds)
-- Access the Control UI from your laptop via an SSH tunnel
-
-That mounted `~/.fengming` state includes `fengming.json`, per-agent
-`agents/<agentId>/agent/auth-profiles.json`, and `.env`.
-
-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 FengMing 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 FengMing repository">
-    ```bash
-    git clone https://github.com/fengming/fengming.git
-    cd fengming
-    ```
-
-    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/.fengming/workspace
-
-    # Set ownership to the container user (uid 1000):
-    chown -R 1000:1000 /root/.fengming
-    ```
-
-  </Step>
-
-  <Step title="Configure environment variables">
-    Create `.env` in the repository root.
-
-    ```bash
-    FENGMING_IMAGE=fengming:latest
-    FENGMING_GATEWAY_TOKEN=
-    FENGMING_GATEWAY_BIND=lan
-    FENGMING_GATEWAY_PORT=18789
-
-    FENGMING_CONFIG_DIR=/root/.fengming
-    FENGMING_WORKSPACE_DIR=/root/.fengming/workspace
-
-    GOG_KEYRING_PASSWORD=
-    XDG_CONFIG_HOME=/home/node/.fengming
-    ```
-
-    Set `FENGMING_GATEWAY_TOKEN` when you want to manage the stable gateway
-    token through `.env`; otherwise configure `gateway.auth.token` before
-    relying on clients across restarts. If neither source exists, FengMing uses
-    a runtime-only token for that startup. Generate a keyring password and paste
-    it into `GOG_KEYRING_PASSWORD`:
-
-    ```bash
-    openssl rand -hex 32
-    ```
-
-    **Do not commit this file.**
-
-    This `.env` file is for container/runtime env such as `FENGMING_GATEWAY_TOKEN`.
-    Stored provider OAuth/API-key auth lives in the mounted
-    `~/.fengming/agents/<agentId>/agent/auth-profiles.json`.
-
-  </Step>
-
-  <Step title="Docker Compose configuration">
-    Create or update `docker-compose.yml`.
-
-    ```yaml
-    services:
-      fengming-gateway:
-        image: ${FENGMING_IMAGE}
-        build: .
-        restart: unless-stopped
-        env_file:
-          - .env
-        environment:
-          - HOME=/home/node
-          - NODE_ENV=production
-          - TERM=xterm-256color
-          - FENGMING_GATEWAY_BIND=${FENGMING_GATEWAY_BIND}
-          - FENGMING_GATEWAY_PORT=${FENGMING_GATEWAY_PORT}
-          - FENGMING_GATEWAY_TOKEN=${FENGMING_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:
-          - ${FENGMING_CONFIG_DIR}:/home/node/.fengming
-          - ${FENGMING_WORKSPACE_DIR}:/home/node/.fengming/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:${FENGMING_GATEWAY_PORT}:18789"
-        command:
-          [
-            "node",
-            "dist/index.js",
-            "gateway",
-            "--bind",
-            "${FENGMING_GATEWAY_BIND}",
-            "--port",
-            "${FENGMING_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, complete the following setup to open the tunnel:
-
-    **Prerequisite:** Ensure your VPS sshd config allows TCP forwarding. If you
-    have hardened your SSH config, check `/etc/ssh/sshd_config` and set:
-
-    ```
-    AllowTcpForwarding local
-    ```
-
-    `local` allows `ssh -L` local forwards from your laptop while blocking
-    remote forwards from the server. Setting it to `no` will fail the tunnel
-    with:
-    `channel 3: open failed: administratively prohibited: open failed`
-
-    After confirming TCP forwarding is enabled, restart the SSH service
-    (`systemctl restart ssh`) and run the 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 the configured shared secret. This guide uses the gateway token by
-    default; if you switched to password auth, use that password instead.
-
-  </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: [fengming-terraform-hetzner](https://github.com/andreesg/fengming-terraform-hetzner)
-- Docker config: [fengming-docker-config](https://github.com/andreesg/fengming-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.
-</Note>
-
-## Next steps
-
-- Set up messaging channels: [Channels](/channels)
-- Configure the Gateway: [Gateway configuration](/gateway/configuration)
-- Keep FengMing up to date: [Updating](/install/updating)
-
-## Related
-
-- [Install overview](/install)
-- [Fly.io](/install/fly)
-- [Docker](/install/docker)
-- [VPS hosting](/vps)