fengming 0.3.9 → 0.3.11

package/docs/install/ansible.md

@@ -1,233 +0,0 @@
----
-summary: "Automated, hardened FengMing installation with Ansible, Tailscale VPN, and firewall isolation"
-read_when:
-  - You want automated server deployment with security hardening
-  - You need firewall-isolated setup with VPN access
-  - You're deploying to remote Debian/Ubuntu servers
-title: "Ansible"
----
-
-Deploy FengMing to production servers with **[fengming-ansible](https://github.com/fengming/fengming-ansible)** -- an automated installer with security-first architecture.
-
-<Info>
-The [fengming-ansible](https://github.com/fengming/fengming-ansible) repo is the source of truth for Ansible deployment. This page is a quick overview.
-</Info>
-
-## Prerequisites
-
-| Requirement | Details                                                   |
-| ----------- | --------------------------------------------------------- |
-| **OS**      | Debian 11+ or Ubuntu 20.04+                               |
-| **Access**  | Root or sudo privileges                                   |
-| **Network** | Internet connection for package installation              |
-| **Ansible** | 2.14+ (installed automatically by the quick-start script) |
-
-## What you get
-
-- **Firewall-first security** -- UFW + Docker isolation (only SSH + Tailscale accessible)
-- **Tailscale VPN** -- secure remote access without exposing services publicly
-- **Docker** -- isolated sandbox containers, localhost-only bindings
-- **Defense in depth** -- 4-layer security architecture
-- **Systemd integration** -- auto-start on boot with hardening
-- **One-command setup** -- complete deployment in minutes
-
-## Quick start
-
-One-command install:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/fengming/fengming-ansible/main/install.sh | bash
-```
-
-## What gets installed
-
-The Ansible playbook installs and configures:
-
-1. **Tailscale** -- mesh VPN for secure remote access
-2. **UFW firewall** -- SSH + Tailscale ports only
-3. **Docker CE + Compose V2** -- for the default agent sandbox backend
-4. **Node.js 24 + pnpm** -- runtime dependencies (Node 22 LTS, currently `22.19+`, remains supported)
-5. **FengMing** -- host-based, not containerized
-6. **Systemd service** -- auto-start with security hardening
-
-<Note>
-The gateway runs directly on the host (not in Docker). Agent sandboxing is
-optional; this playbook installs Docker because it is the default sandbox
-backend. See [Sandboxing](/gateway/sandboxing) for details and other backends.
-</Note>
-
-## Post-Install Setup
-
-<Steps>
-  <Step title="Switch to the fengming user">
-    ```bash
-    sudo -i -u fengming
-    ```
-  </Step>
-  <Step title="Run the onboarding wizard">
-    The post-install script guides you through configuring FengMing settings.
-  </Step>
-  <Step title="Connect messaging providers">
-    Log in to WhatsApp, Telegram, Discord, or Signal:
-    ```bash
-    fengming channels login
-    ```
-  </Step>
-  <Step title="Verify the installation">
-    ```bash
-    sudo systemctl status fengming
-    sudo journalctl -u fengming -f
-    ```
-  </Step>
-  <Step title="Connect to Tailscale">
-    Join your VPN mesh for secure remote access.
-  </Step>
-</Steps>
-
-### Quick commands
-
-```bash
-# Check service status
-sudo systemctl status fengming
-
-# View live logs
-sudo journalctl -u fengming -f
-
-# Restart gateway
-sudo systemctl restart fengming
-
-# Provider login (run as fengming user)
-sudo -i -u fengming
-fengming channels login
-```
-
-## Security architecture
-
-The deployment uses a 4-layer defense model:
-
-1. **Firewall (UFW)** -- only SSH (22) + Tailscale (41641/udp) exposed publicly
-2. **VPN (Tailscale)** -- gateway accessible only via VPN mesh
-3. **Docker isolation** -- DOCKER-USER iptables chain prevents external port exposure
-4. **Systemd hardening** -- NoNewPrivileges, PrivateTmp, unprivileged user
-
-To verify your external attack surface:
-
-```bash
-nmap -p- YOUR_SERVER_IP
-```
-
-Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down.
-
-Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration.
-
-## Manual installation
-
-If you prefer manual control over the automation:
-
-<Steps>
-  <Step title="Install prerequisites">
-    ```bash
-    sudo apt update && sudo apt install -y ansible git
-    ```
-  </Step>
-  <Step title="Clone the repository">
-    ```bash
-    git clone https://github.com/fengming/fengming-ansible.git
-    cd fengming-ansible
-    ```
-  </Step>
-  <Step title="Install Ansible collections">
-    ```bash
-    ansible-galaxy collection install -r requirements.yml
-    ```
-  </Step>
-  <Step title="Run the playbook">
-    ```bash
-    ./run-playbook.sh
-    ```
-
-    Alternatively, run directly and then manually execute the setup script afterward:
-    ```bash
-    ansible-playbook playbook.yml --ask-become-pass
-    # Then run: /tmp/fengming-setup.sh
-    ```
-
-  </Step>
-</Steps>
-
-## Updating
-
-The Ansible installer sets up FengMing for manual updates. See [Updating](/install/updating) for the standard update flow.
-
-To re-run the Ansible playbook (for example, for configuration changes):
-
-```bash
-cd fengming-ansible
-./run-playbook.sh
-```
-
-This is idempotent and safe to run multiple times.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="Firewall blocks my connection">
-    - Ensure you can access via Tailscale VPN first
-    - SSH access (port 22) is always allowed
-    - The gateway is only accessible via Tailscale by design
-
-  </Accordion>
-  <Accordion title="Service will not start">
-    ```bash
-    # Check logs
-    sudo journalctl -u fengming -n 100
-
-    # Verify permissions
-    sudo ls -la /opt/fengming
-
-    # Test manual start
-    sudo -i -u fengming
-    cd ~/fengming
-    fengming gateway run
-    ```
-
-  </Accordion>
-  <Accordion title="Docker sandbox issues">
-    ```bash
-    # Verify Docker is running
-    sudo systemctl status docker
-
-    # Check sandbox image
-    sudo docker images | grep fengming-sandbox
-
-    # Build sandbox image if missing (requires source checkout)
-    cd /opt/fengming/fengming
-    sudo -u fengming ./scripts/sandbox-setup.sh
-    # For npm installs without a source checkout, see
-    # https://docs.fengming.ai/gateway/sandboxing#images-and-setup
-    ```
-
-  </Accordion>
-  <Accordion title="Provider login fails">
-    Make sure you are running as the `fengming` user:
-    ```bash
-    sudo -i -u fengming
-    fengming channels login
-    ```
-  </Accordion>
-</AccordionGroup>
-
-## Advanced configuration
-
-For detailed security architecture and troubleshooting, see the fengming-ansible repo:
-
-- [Security Architecture](https://github.com/fengming/fengming-ansible/blob/main/docs/security.md)
-- [Technical Details](https://github.com/fengming/fengming-ansible/blob/main/docs/architecture.md)
-- [Troubleshooting Guide](https://github.com/fengming/fengming-ansible/blob/main/docs/troubleshooting.md)
-
-## Related
-
-- [fengming-ansible](https://github.com/fengming/fengming-ansible) -- full deployment guide
-- [Docker](/install/docker) -- containerized gateway setup
-- [Sandboxing](/gateway/sandboxing) -- agent sandbox configuration
-- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- per-agent isolation

package/docs/install/azure.md

@@ -1,315 +0,0 @@
----
-summary: "Run FengMing Gateway 24/7 on an Azure Linux VM with durable state"
-read_when:
-  - You want FengMing running 24/7 on Azure with Network Security Group hardening
-  - You want a production-grade, always-on FengMing Gateway on your own Azure Linux VM
-  - You want secure administration with Azure Bastion SSH
-title: "Azure"
----
-
-This guide sets up an Azure Linux VM with the Azure CLI, applies Network Security Group (NSG) hardening, configures Azure Bastion for SSH access, and installs FengMing.
-
-## What you will do
-
-- Create Azure networking (VNet, subnets, NSG) and compute resources with the Azure CLI
-- Apply Network Security Group rules so VM SSH is allowed only from Azure Bastion
-- Use Azure Bastion for SSH access (no public IP on the VM)
-- Install FengMing with the installer script
-- Verify the Gateway
-
-## What you need
-
-- An Azure subscription with permission to create compute and network resources
-- Azure CLI installed (see [Azure CLI install steps](https://learn.microsoft.com/cli/azure/install-azure-cli) if needed)
-- An SSH key pair (the guide covers generating one if needed)
-- ~20-30 minutes
-
-## Configure deployment
-
-<Steps>
-  <Step title="Sign in to Azure CLI">
-    ```bash
-    az login
-    az extension add -n ssh
-    ```
-
-    The `ssh` extension is required for Azure Bastion native SSH tunneling.
-
-  </Step>
-
-  <Step title="Register required resource providers (one-time)">
-    ```bash
-    az provider register --namespace Microsoft.Compute
-    az provider register --namespace Microsoft.Network
-    ```
-
-    Verify registration. Wait until both show `Registered`.
-
-    ```bash
-    az provider show --namespace Microsoft.Compute --query registrationState -o tsv
-    az provider show --namespace Microsoft.Network --query registrationState -o tsv
-    ```
-
-  </Step>
-
-  <Step title="Set deployment variables">
-    ```bash
-    RG="rg-fengming"
-    LOCATION="westus2"
-    VNET_NAME="vnet-fengming"
-    VNET_PREFIX="10.40.0.0/16"
-    VM_SUBNET_NAME="snet-fengming-vm"
-    VM_SUBNET_PREFIX="10.40.2.0/24"
-    BASTION_SUBNET_PREFIX="10.40.1.0/26"
-    NSG_NAME="nsg-fengming-vm"
-    VM_NAME="vm-fengming"
-    ADMIN_USERNAME="fengming"
-    BASTION_NAME="bas-fengming"
-    BASTION_PIP_NAME="pip-fengming-bastion"
-    ```
-
-    Adjust names and CIDR ranges to fit your environment. The Bastion subnet must be at least `/26`.
-
-  </Step>
-
-  <Step title="Select SSH key">
-    Use your existing public key if you have one:
-
-    ```bash
-    SSH_PUB_KEY="$(cat ~/.ssh/id_ed25519.pub)"
-    ```
-
-    If you don't have an SSH key yet, generate one:
-
-    ```bash
-    ssh-keygen -t ed25519 -a 100 -f ~/.ssh/id_ed25519 -C "you@example.com"
-    SSH_PUB_KEY="$(cat ~/.ssh/id_ed25519.pub)"
-    ```
-
-  </Step>
-
-  <Step title="Select VM size and OS disk size">
-    ```bash
-    VM_SIZE="Standard_B2as_v2"
-    OS_DISK_SIZE_GB=64
-    ```
-
-    Choose a VM size and OS disk size available in your subscription and region:
-
-    - Start smaller for light usage and scale up later
-    - Use more vCPU/RAM/disk for heavier automation, more channels, or larger model/tool workloads
-    - If a VM size is unavailable in your region or subscription quota, pick the closest available SKU
-
-    List VM sizes available in your target region:
-
-    ```bash
-    az vm list-skus --location "${LOCATION}" --resource-type virtualMachines -o table
-    ```
-
-    Check your current vCPU and disk usage/quota:
-
-    ```bash
-    az vm list-usage --location "${LOCATION}" -o table
-    ```
-
-  </Step>
-</Steps>
-
-## Deploy Azure resources
-
-<Steps>
-  <Step title="Create the resource group">
-    ```bash
-    az group create -n "${RG}" -l "${LOCATION}"
-    ```
-  </Step>
-
-  <Step title="Create the network security group">
-    Create the NSG and add rules so only the Bastion subnet can SSH into the VM.
-
-    ```bash
-    az network nsg create \
-      -g "${RG}" -n "${NSG_NAME}" -l "${LOCATION}"
-
-    # Allow SSH from the Bastion subnet only
-    az network nsg rule create \
-      -g "${RG}" --nsg-name "${NSG_NAME}" \
-      -n AllowSshFromBastionSubnet --priority 100 \
-      --access Allow --direction Inbound --protocol Tcp \
-      --source-address-prefixes "${BASTION_SUBNET_PREFIX}" \
-      --destination-port-ranges 22
-
-    # Deny SSH from the public internet
-    az network nsg rule create \
-      -g "${RG}" --nsg-name "${NSG_NAME}" \
-      -n DenyInternetSsh --priority 110 \
-      --access Deny --direction Inbound --protocol Tcp \
-      --source-address-prefixes Internet \
-      --destination-port-ranges 22
-
-    # Deny SSH from other VNet sources
-    az network nsg rule create \
-      -g "${RG}" --nsg-name "${NSG_NAME}" \
-      -n DenyVnetSsh --priority 120 \
-      --access Deny --direction Inbound --protocol Tcp \
-      --source-address-prefixes VirtualNetwork \
-      --destination-port-ranges 22
-    ```
-
-    The rules are evaluated by priority (lowest number first): Bastion traffic is allowed at 100, then all other SSH is blocked at 110 and 120.
-
-  </Step>
-
-  <Step title="Create the virtual network and subnets">
-    Create the VNet with the VM subnet (NSG attached), then add the Bastion subnet.
-
-    ```bash
-    az network vnet create \
-      -g "${RG}" -n "${VNET_NAME}" -l "${LOCATION}" \
-      --address-prefixes "${VNET_PREFIX}" \
-      --subnet-name "${VM_SUBNET_NAME}" \
-      --subnet-prefixes "${VM_SUBNET_PREFIX}"
-
-    # Attach the NSG to the VM subnet
-    az network vnet subnet update \
-      -g "${RG}" --vnet-name "${VNET_NAME}" \
-      -n "${VM_SUBNET_NAME}" --nsg "${NSG_NAME}"
-
-    # AzureBastionSubnet — name is required by Azure
-    az network vnet subnet create \
-      -g "${RG}" --vnet-name "${VNET_NAME}" \
-      -n AzureBastionSubnet \
-      --address-prefixes "${BASTION_SUBNET_PREFIX}"
-    ```
-
-  </Step>
-
-  <Step title="Create the VM">
-    The VM has no public IP. SSH access is exclusively through Azure Bastion.
-
-    ```bash
-    az vm create \
-      -g "${RG}" -n "${VM_NAME}" -l "${LOCATION}" \
-      --image "Canonical:ubuntu-24_04-lts:server:latest" \
-      --size "${VM_SIZE}" \
-      --os-disk-size-gb "${OS_DISK_SIZE_GB}" \
-      --storage-sku StandardSSD_LRS \
-      --admin-username "${ADMIN_USERNAME}" \
-      --ssh-key-values "${SSH_PUB_KEY}" \
-      --vnet-name "${VNET_NAME}" \
-      --subnet "${VM_SUBNET_NAME}" \
-      --public-ip-address "" \
-      --nsg ""
-    ```
-
-    `--public-ip-address ""` prevents a public IP from being assigned. `--nsg ""` skips creating a per-NIC NSG (the subnet-level NSG handles security).
-
-    **Reproducibility:** The command above uses `latest` for the Ubuntu image. To pin a specific version, list available versions and replace `latest`:
-
-    ```bash
-    az vm image list \
-      --publisher Canonical --offer ubuntu-24_04-lts \
-      --sku server --all -o table
-    ```
-
-  </Step>
-
-  <Step title="Create Azure Bastion">
-    Azure Bastion provides managed SSH access to the VM without exposing a public IP. Standard SKU with tunneling is required for CLI-based `az network bastion ssh`.
-
-    ```bash
-    az network public-ip create \
-      -g "${RG}" -n "${BASTION_PIP_NAME}" -l "${LOCATION}" \
-      --sku Standard --allocation-method Static
-
-    az network bastion create \
-      -g "${RG}" -n "${BASTION_NAME}" -l "${LOCATION}" \
-      --vnet-name "${VNET_NAME}" \
-      --public-ip-address "${BASTION_PIP_NAME}" \
-      --sku Standard --enable-tunneling true
-    ```
-
-    Bastion provisioning typically takes 5-10 minutes but can take up to 15-30 minutes in some regions.
-
-  </Step>
-</Steps>
-
-## Install FengMing
-
-<Steps>
-  <Step title="SSH into the VM through Azure Bastion">
-    ```bash
-    VM_ID="$(az vm show -g "${RG}" -n "${VM_NAME}" --query id -o tsv)"
-
-    az network bastion ssh \
-      --name "${BASTION_NAME}" \
-      --resource-group "${RG}" \
-      --target-resource-id "${VM_ID}" \
-      --auth-type ssh-key \
-      --username "${ADMIN_USERNAME}" \
-      --ssh-key ~/.ssh/id_ed25519
-    ```
-
-  </Step>
-
-  <Step title="Install FengMing (in the VM shell)">
-    ```bash
-    curl -fsSL https://fengming.ai/install.sh -o /tmp/install.sh
-    bash /tmp/install.sh
-    rm -f /tmp/install.sh
-    ```
-
-    The installer installs Node LTS and dependencies if not already present, installs FengMing, and launches the onboarding wizard. See [Install](/install) for details.
-
-  </Step>
-
-  <Step title="Verify the Gateway">
-    After onboarding completes:
-
-    ```bash
-    fengming gateway status
-    ```
-
-    Most enterprise Azure teams already have GitHub Copilot licenses. If that is your case, we recommend choosing the GitHub Copilot provider in the FengMing onboarding wizard. See [GitHub Copilot provider](/providers/github-copilot).
-
-  </Step>
-</Steps>
-
-## Cost considerations
-
-Azure Bastion Standard SKU runs approximately **\$140/month** and the VM (Standard_B2as_v2) runs approximately **\$55/month**.
-
-To reduce costs:
-
-- **Deallocate the VM** when not in use (stops compute billing; disk charges remain). The FengMing Gateway will not be reachable while the VM is deallocated — restart it when you need it live again:
-
-  ```bash
-  az vm deallocate -g "${RG}" -n "${VM_NAME}"
-  az vm start -g "${RG}" -n "${VM_NAME}"   # restart later
-  ```
-
-- **Delete Bastion when not needed** and recreate it when you need SSH access. Bastion is the largest cost component and takes only a few minutes to provision.
-- **Use the Basic Bastion SKU** (~\$38/month) if you only need Portal-based SSH and don't require CLI tunneling (`az network bastion ssh`).
-
-## Cleanup
-
-To delete all resources created by this guide:
-
-```bash
-az group delete -n "${RG}" --yes --no-wait
-```
-
-This removes the resource group and everything inside it (VM, VNet, NSG, Bastion, public IP).
-
-## Next steps
-
-- Set up messaging channels: [Channels](/channels)
-- Pair local devices as nodes: [Nodes](/nodes)
-- Configure the Gateway: [Gateway configuration](/gateway/configuration)
-- For more details on FengMing Azure deployment with the GitHub Copilot model provider: [FengMing on Azure with GitHub Copilot](https://github.com/johnsonshi/fengming-azure-github-copilot)
-
-## Related
-
-- [Install overview](/install)
-- [GCP](/install/gcp)
-- [DigitalOcean](/install/digitalocean)

package/docs/install/bun.md

@@ -1,59 +0,0 @@
----
-summary: "Bun workflow (experimental): installs and gotchas vs pnpm"
-read_when:
-  - You want the fastest local dev loop (bun + watch)
-  - You hit Bun install/patch/lifecycle script issues
-title: "Bun (experimental)"
----
-
-<Warning>
-Bun is **not recommended for gateway runtime** (known issues with WhatsApp and Telegram). Use Node for production.
-</Warning>
-
-Bun is an optional local runtime for running TypeScript directly (`bun run ...`, `bun --watch ...`). The default package manager remains `pnpm`, which is fully supported and used by docs tooling. Bun cannot use `pnpm-lock.yaml` and will ignore it.
-
-## Install
-
-<Steps>
-  <Step title="Install dependencies">
-    ```sh
-    bun install
-    ```
-
-    `bun.lock` / `bun.lockb` are gitignored, so there is no repo churn. To skip lockfile writes entirely:
-
-    ```sh
-    bun install --no-save
-    ```
-
-  </Step>
-  <Step title="Build and test">
-    ```sh
-    bun run build
-    bun run vitest run
-    ```
-  </Step>
-</Steps>
-
-## Lifecycle scripts
-
-Bun blocks dependency lifecycle scripts unless explicitly trusted. For this repo, the commonly blocked scripts are not required:
-
-- `baileys` `preinstall` -- checks Node major >= 20 (FengMing defaults to Node 24 and still supports Node 22 LTS, currently `22.19+`)
-- `protobufjs` `postinstall` -- emits warnings about incompatible version schemes (no build artifacts)
-
-If you hit a runtime issue that requires these scripts, trust them explicitly:
-
-```sh
-bun pm trust baileys protobufjs
-```
-
-## Caveats
-
-Some scripts still hardcode pnpm (for example `check:docs`, `ui:*`, `protocol:check`). Run those via pnpm for now.
-
-## Related
-
-- [Install overview](/install)
-- [Node.js](/install/node)
-- [Updating](/install/updating)