@quantumclaw/quantumclaw 2026.3.22

package/docs/install/ansible.md

@@ -0,0 +1,230 @@
+---
+summary: "Automated, hardened QuantumClaw 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"
+---
+
+# Ansible Installation
+
+Deploy QuantumClaw to production servers with **[quantumclaw-ansible](https://github.com/quantumclaw/quantumclaw-ansible)** -- an automated installer with security-first architecture.
+
+<Info>
+The [quantumclaw-ansible](https://github.com/quantumclaw/quantumclaw-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/quantumclaw/quantumclaw-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 agent sandboxes
+4. **Node.js 24 + pnpm** -- runtime dependencies (Node 22 LTS, currently `22.16+`, remains supported)
+5. **QuantumClaw** -- host-based, not containerized
+6. **Systemd service** -- auto-start with security hardening
+
+<Note>
+The gateway runs directly on the host (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
+</Note>
+
+## Post-Install Setup
+
+<Steps>
+  <Step title="Switch to the quantumclaw user">
+    ```bash
+    sudo -i -u quantumclaw
+    ```
+  </Step>
+  <Step title="Run the onboarding wizard">
+    The post-install script guides you through configuring QuantumClaw settings.
+  </Step>
+  <Step title="Connect messaging providers">
+    Log in to WhatsApp, Telegram, Discord, or Signal:
+    ```bash
+    quantumclaw channels login
+    ```
+  </Step>
+  <Step title="Verify the installation">
+    ```bash
+    sudo systemctl status quantumclaw
+    sudo journalctl -u quantumclaw -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 quantumclaw
+
+# View live logs
+sudo journalctl -u quantumclaw -f
+
+# Restart gateway
+sudo systemctl restart quantumclaw
+
+# Provider login (run as quantumclaw user)
+sudo -i -u quantumclaw
+quantumclaw 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/quantumclaw/quantumclaw-ansible.git
+    cd quantumclaw-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/quantumclaw-setup.sh
+    ```
+
+  </Step>
+</Steps>
+
+## Updating
+
+The Ansible installer sets up QuantumClaw 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 quantumclaw-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 quantumclaw -n 100
+
+    # Verify permissions
+    sudo ls -la /opt/quantumclaw
+
+    # Test manual start
+    sudo -i -u quantumclaw
+    cd ~/quantumclaw
+    quantumclaw gateway run
+    ```
+
+  </Accordion>
+  <Accordion title="Docker sandbox issues">
+    ```bash
+    # Verify Docker is running
+    sudo systemctl status docker
+
+    # Check sandbox image
+    sudo docker images | grep quantumclaw-sandbox
+
+    # Build sandbox image if missing
+    cd /opt/quantumclaw/quantumclaw
+    sudo -u quantumclaw ./scripts/sandbox-setup.sh
+    ```
+
+  </Accordion>
+  <Accordion title="Provider login fails">
+    Make sure you are running as the `quantumclaw` user:
+    ```bash
+    sudo -i -u quantumclaw
+    quantumclaw channels login
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Advanced Configuration
+
+For detailed security architecture and troubleshooting, see the quantumclaw-ansible repo:
+
+- [Security Architecture](https://github.com/quantumclaw/quantumclaw-ansible/blob/main/docs/security.md)
+- [Technical Details](https://github.com/quantumclaw/quantumclaw-ansible/blob/main/docs/architecture.md)
+- [Troubleshooting Guide](https://github.com/quantumclaw/quantumclaw-ansible/blob/main/docs/troubleshooting.md)
+
+## Related
+
+- [quantumclaw-ansible](https://github.com/quantumclaw/quantumclaw-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

@@ -0,0 +1,311 @@
+---
+summary: "Run QuantumClaw Gateway 24/7 on an Azure Linux VM with durable state"
+read_when:
+  - You want QuantumClaw running 24/7 on Azure with Network Security Group hardening
+  - You want a production-grade, always-on QuantumClaw Gateway on your own Azure Linux VM
+  - You want secure administration with Azure Bastion SSH
+title: "Azure"
+---
+
+# QuantumClaw on Azure Linux VM
+
+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 QuantumClaw.
+
+## What you'll 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 QuantumClaw 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-quantumclaw"
+    LOCATION="westus2"
+    VNET_NAME="vnet-quantumclaw"
+    VNET_PREFIX="10.40.0.0/16"
+    VM_SUBNET_NAME="snet-quantumclaw-vm"
+    VM_SUBNET_PREFIX="10.40.2.0/24"
+    BASTION_SUBNET_PREFIX="10.40.1.0/26"
+    NSG_NAME="nsg-quantumclaw-vm"
+    VM_NAME="vm-quantumclaw"
+    ADMIN_USERNAME="quantumclaw"
+    BASTION_NAME="bas-quantumclaw"
+    BASTION_PIP_NAME="pip-quantumclaw-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 QuantumClaw
+
+<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 QuantumClaw (in the VM shell)">
+    ```bash
+    curl -fsSL https://quantumclaw.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 QuantumClaw, and launches the onboarding wizard. See [Install](/install) for details.
+
+  </Step>
+
+  <Step title="Verify the Gateway">
+    After onboarding completes:
+
+    ```bash
+    quantumclaw 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 QuantumClaw 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 QuantumClaw 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 QuantumClaw Azure deployment with the GitHub Copilot model provider: [QuantumClaw on Azure with GitHub Copilot](https://github.com/johnsonshi/quantumclaw-azure-github-copilot)

package/docs/install/bun.md

@@ -0,0 +1,55 @@
+---
+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)"
+---
+
+# 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:
+
+- `@whiskeysockets/baileys` `preinstall` -- checks Node major >= 20 (QuantumClaw defaults to Node 24 and still supports Node 22 LTS, currently `22.16+`)
+- `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 @whiskeysockets/baileys protobufjs
+```
+
+## Caveats
+
+Some scripts still hardcode pnpm (for example `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now.