durar-ai 2026.4.4

package/docs/install/raspberry-pi.md

@@ -0,0 +1,159 @@
+---
+summary: "Host Durar on a Raspberry Pi for always-on self-hosting"
+read_when:
+  - Setting up Durar on a Raspberry Pi
+  - Running Durar on ARM devices
+  - Building a cheap always-on personal AI
+title: "Raspberry Pi"
+---
+
+# Raspberry Pi
+
+Run a persistent, always-on Durar Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well.
+
+## Prerequisites
+
+- Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
+- MicroSD card (16 GB+) or USB SSD (better performance)
+- Official Pi power supply
+- Network connection (Ethernet or WiFi)
+- 64-bit Raspberry Pi OS (required -- do not use 32-bit)
+- About 30 minutes
+
+## Setup
+
+<Steps>
+  <Step title="Flash the OS">
+    Use **Raspberry Pi OS Lite (64-bit)** -- no desktop needed for a headless server.
+
+    1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
+    2. Choose OS: **Raspberry Pi OS Lite (64-bit)**.
+    3. In the settings dialog, pre-configure:
+       - Hostname: `gateway-host`
+       - Enable SSH
+       - Set username and password
+       - Configure WiFi (if not using Ethernet)
+    4. Flash to your SD card or USB drive, insert it, and boot the Pi.
+
+  </Step>
+
+  <Step title="Connect via SSH">
+    ```bash
+    ssh user@gateway-host
+    ```
+  </Step>
+
+  <Step title="Update the system">
+    ```bash
+    sudo apt update && sudo apt upgrade -y
+    sudo apt install -y git curl build-essential
+
+    # Set timezone (important for cron and reminders)
+    sudo timedatectl set-timezone America/Chicago
+    ```
+
+  </Step>
+
+  <Step title="Install Node.js 24">
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+    sudo apt install -y nodejs
+    node --version
+    ```
+  </Step>
+
+  <Step title="Add swap (important for 2 GB or less)">
+    ```bash
+    sudo fallocate -l 2G /swapfile
+    sudo chmod 600 /swapfile
+    sudo mkswap /swapfile
+    sudo swapon /swapfile
+    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+    # Reduce swappiness for low-RAM devices
+    echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
+    sudo sysctl -p
+    ```
+
+  </Step>
+
+  <Step title="Install Durar">
+    ```bash
+    curl -fsSL https://Durar.ai/install.sh | bash
+    ```
+  </Step>
+
+  <Step title="Run onboarding">
+    ```bash
+    Durar onboard --install-daemon
+    ```
+
+    Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.
+
+  </Step>
+
+  <Step title="Verify">
+    ```bash
+    Durar status
+    systemctl --user status Durar-gateway.service
+    journalctl --user -u Durar-gateway.service -f
+    ```
+  </Step>
+
+  <Step title="Access the Control UI">
+    On your computer, get a dashboard URL from the Pi:
+
+    ```bash
+    ssh user@gateway-host 'Durar dashboard --no-open'
+    ```
+
+    Then create an SSH tunnel in another terminal:
+
+    ```bash
+    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
+    ```
+
+    Open the printed URL in your local browser. For always-on remote access, see [Tailscale integration](/gateway/tailscale).
+
+  </Step>
+</Steps>
+
+## Performance tips
+
+**Use a USB SSD** -- SD cards are slow and wear out. A USB SSD dramatically improves performance. See the [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot).
+
+**Enable module compile cache** -- Speeds up repeated CLI invocations on lower-power Pi hosts:
+
+```bash
+grep -q 'NODE_COMPILE_CACHE=/var/tmp/Durar-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
+export NODE_COMPILE_CACHE=/var/tmp/Durar-compile-cache
+mkdir -p /var/tmp/Durar-compile-cache
+export Durar_NO_RESPAWN=1
+EOF
+source ~/.bashrc
+```
+
+**Reduce memory usage** -- For headless setups, free GPU memory and disable unused services:
+
+```bash
+echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
+sudo systemctl disable bluetooth
+```
+
+## Troubleshooting
+
+**Out of memory** -- Verify swap is active with `free -h`. Disable unused services (`sudo systemctl disable cups bluetooth avahi-daemon`). Use API-based models only.
+
+**Slow performance** -- Use a USB SSD instead of an SD card. Check for CPU throttling with `vcgencmd get_throttled` (should return `0x0`).
+
+**Service will not start** -- Check logs with `journalctl --user -u Durar-gateway.service --no-pager -n 100` and run `Durar doctor --non-interactive`. If this is a headless Pi, also verify lingering is enabled: `sudo loginctl enable-linger "$(whoami)"`.
+
+**ARM binary issues** -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with `uname -m` (should show `aarch64`).
+
+**WiFi drops** -- Disable WiFi power management: `sudo iwconfig wlan0 power off`.
+
+## Next steps
+
+- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
+- [Gateway configuration](/gateway/configuration) -- all config options
+- [Updating](/install/updating) -- keep Durar up to date

package/docs/install/render.mdx

@@ -0,0 +1,165 @@
+---
+summary: "Deploy OpenClaw on Render with Infrastructure-as-Code"
+read_when:
+  - Deploying OpenClaw to Render
+  - You want a declarative cloud deploy with Render Blueprints
+title: "Render"
+---
+
+Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yaml` Blueprint defines your entire stack declaratively, service, disk, environment variables, so you can deploy with a single click and version your infrastructure alongside your code.
+
+## Prerequisites
+
+- A [Render account](https://render.com) (free tier available)
+- An API key from your preferred [model provider](/providers)
+
+## Deploy with a Render Blueprint
+
+[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
+
+Clicking this link will:
+
+1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
+2. Build the Docker image and deploy
+
+Once deployed, your service URL follows the pattern `https://<service-name>.onrender.com`.
+
+## Understanding the Blueprint
+
+Render Blueprints are YAML files that define your infrastructure. The `render.yaml` in this
+repository configures everything needed to run OpenClaw:
+
+```yaml
+services:
+  - type: web
+    name: openclaw
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: OPENCLAW_GATEWAY_PORT
+        value: "8080"
+      - key: OPENCLAW_STATE_DIR
+        value: /data/.openclaw
+      - key: OPENCLAW_WORKSPACE_DIR
+        value: /data/workspace
+      - key: OPENCLAW_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: openclaw-data
+      mountPath: /data
+      sizeGB: 1
+```
+
+Key Blueprint features used:
+
+| Feature               | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `runtime: docker`     | Builds from the repo's Dockerfile                          |
+| `healthCheckPath`     | Render monitors `/health` and restarts unhealthy instances |
+| `generateValue: true` | Auto-generates a cryptographically secure value            |
+| `disk`                | Persistent storage that survives redeploys                 |
+
+## Choosing a plan
+
+| Plan      | Spin-down         | Disk          | Best for                      |
+| --------- | ----------------- | ------------- | ----------------------------- |
+| Free      | After 15 min idle | Not available | Testing, demos                |
+| Starter   | Never             | 1GB+          | Personal use, small teams     |
+| Standard+ | Never             | 1GB+          | Production, multiple channels |
+
+The Blueprint defaults to `starter`. To use free tier, change `plan: free` in
+your fork's `render.yaml` (but note: no persistent disk means OpenClaw state
+resets on each deploy).
+
+## After deployment
+
+### Access the Control UI
+
+The web dashboard is available at `https://<your-service>.onrender.com/`.
+
+Connect using the configured shared secret. This deploy template auto-generates
+`OPENCLAW_GATEWAY_TOKEN` (find it in **Dashboard → your service →
+Environment**); if you replace it with password auth, use that password
+instead.
+
+## Render Dashboard features
+
+### Logs
+
+View real-time logs in **Dashboard → your service → Logs**. Filter by:
+
+- Build logs (Docker image creation)
+- Deploy logs (service startup)
+- Runtime logs (application output)
+
+### Shell access
+
+For debugging, open a shell session via **Dashboard → your service → Shell**. The persistent disk is mounted at `/data`.
+
+### Environment variables
+
+Modify variables in **Dashboard → your service → Environment**. Changes trigger an automatic redeploy.
+
+### Auto-deploy
+
+If you use the original OpenClaw repository, Render will not auto-deploy your OpenClaw. To update it, run a manual Blueprint sync from the dashboard.
+
+## Custom domain
+
+1. Go to **Dashboard → your service → Settings → Custom Domains**
+2. Add your domain
+3. Configure DNS as instructed (CNAME to `*.onrender.com`)
+4. Render provisions a TLS certificate automatically
+
+## Scaling
+
+Render supports horizontal and vertical scaling:
+
+- **Vertical**: Change the plan to get more CPU/RAM
+- **Horizontal**: Increase instance count (Standard plan and above)
+
+For OpenClaw, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.
+
+## Backups and migration
+
+Export your state, config, auth profiles, and workspace at any time using the
+shell access in the Render Dashboard:
+
+```bash
+openclaw backup create
+```
+
+This creates a portable backup archive with OpenClaw state plus any configured
+workspace. See [Backup](/cli/backup) for details.
+
+## Troubleshooting
+
+### Service will not start
+
+Check the deploy logs in the Render Dashboard. Common issues:
+
+- Missing `OPENCLAW_GATEWAY_TOKEN` — verify it is set in **Dashboard → Environment**
+- Port mismatch — ensure `OPENCLAW_GATEWAY_PORT=8080` is set so the gateway binds to the port Render expects
+
+### Slow cold starts (free tier)
+
+Free tier services spin down after 15 minutes of inactivity. The first request after spin-down takes a few seconds while the container starts. Upgrade to Starter plan for always-on.
+
+### Data loss after redeploy
+
+This happens on free tier (no persistent disk). Upgrade to a paid plan, or
+regularly export a full backup via `openclaw backup create` in the Render shell.
+
+### Health check failures
+
+Render expects a 200 response from `/health` within 30 seconds. If builds succeed but deploys fail, the service may be taking too long to start. Check:
+
+- Build logs for errors
+- Whether the container runs locally with `docker build && docker run`
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep OpenClaw up to date: [Updating](/install/updating)

package/docs/install/uninstall.md

@@ -0,0 +1,128 @@
+---
+summary: "Uninstall Durar completely (CLI, service, state, workspace)"
+read_when:
+  - You want to remove Durar from a machine
+  - The gateway service is still running after uninstall
+title: "Uninstall"
+---
+
+# Uninstall
+
+Two paths:
+
+- **Easy path** if `Durar` is still installed.
+- **Manual service removal** if the CLI is gone but the service is still running.
+
+## Easy path (CLI still installed)
+
+Recommended: use the built-in uninstaller:
+
+```bash
+Durar uninstall
+```
+
+Non-interactive (automation / npx):
+
+```bash
+Durar uninstall --all --yes --non-interactive
+npx -y Durar uninstall --all --yes --non-interactive
+```
+
+Manual steps (same result):
+
+1. Stop the gateway service:
+
+```bash
+Durar gateway stop
+```
+
+2. Uninstall the gateway service (launchd/systemd/schtasks):
+
+```bash
+Durar gateway uninstall
+```
+
+3. Delete state + config:
+
+```bash
+rm -rf "${Durar_STATE_DIR:-$HOME/.Durar}"
+```
+
+If you set `Durar_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
+
+4. Delete your workspace (optional, removes agent files):
+
+```bash
+rm -rf ~/.Durar/workspace
+```
+
+5. Remove the CLI install (pick the one you used):
+
+```bash
+npm rm -g Durar
+pnpm remove -g Durar
+bun remove -g Durar
+```
+
+6. If you installed the macOS app:
+
+```bash
+rm -rf /Applications/Durar.app
+```
+
+Notes:
+
+- If you used profiles (`--profile` / `Durar_PROFILE`), repeat step 3 for each state dir (defaults are `~/.Durar-<profile>`).
+- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
+
+## Manual service removal (CLI not installed)
+
+Use this if the gateway service keeps running but `Durar` is missing.
+
+### macOS (launchd)
+
+Default label is `ai.Durar.gateway` (or `ai.Durar.<profile>`; legacy `com.Durar.*` may still exist):
+
+```bash
+launchctl bootout gui/$UID/ai.Durar.gateway
+rm -f ~/Library/LaunchAgents/ai.Durar.gateway.plist
+```
+
+If you used a profile, replace the label and plist name with `ai.Durar.<profile>`. Remove any legacy `com.Durar.*` plists if present.
+
+### Linux (systemd user unit)
+
+Default unit name is `Durar-gateway.service` (or `Durar-gateway-<profile>.service`):
+
+```bash
+systemctl --user disable --now Durar-gateway.service
+rm -f ~/.config/systemd/user/Durar-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows (Scheduled Task)
+
+Default task name is `Durar Gateway` (or `Durar Gateway (<profile>)`).
+The task script lives under your state dir.
+
+```powershell
+schtasks /Delete /F /TN "Durar Gateway"
+Remove-Item -Force "$env:USERPROFILE\.Durar\gateway.cmd"
+```
+
+If you used a profile, delete the matching task name and `~\.Durar-<profile>\gateway.cmd`.
+
+## Normal install vs source checkout
+
+### Normal install (install.sh / npm / pnpm / bun)
+
+If you used `https://Durar.ai/install.sh` or `install.ps1`, the CLI was installed with `npm install -g Durar@latest`.
+Remove it with `npm rm -g Durar` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
+
+### Source checkout (git clone)
+
+If you run from a repo checkout (`git clone` + `Durar ...` / `bun run Durar ...`):
+
+1. Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
+2. Delete the repo directory.
+3. Remove state + workspace as shown above.

package/docs/install/updating.md

@@ -0,0 +1,142 @@
+---
+summary: "Updating Durar safely (global install or source), plus rollback strategy"
+read_when:
+  - Updating Durar
+  - Something breaks after an update
+title: "Updating"
+---
+
+# Updating
+
+Keep Durar up to date.
+
+## Recommended: `Durar update`
+
+The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `Durar doctor`, and restarts the gateway.
+
+```bash
+Durar update
+```
+
+To switch channels or target a specific version:
+
+```bash
+Durar update --channel beta
+Durar update --tag main
+Durar update --dry-run   # preview without applying
+```
+
+`--channel beta` prefers beta, but the runtime falls back to stable/latest when
+the beta tag is missing or older than the latest stable release. Use `--tag beta`
+if you want the raw npm beta dist-tag for a one-off package update.
+
+See [Development channels](/install/development-channels) for channel semantics.
+
+## Alternative: re-run the installer
+
+```bash
+curl -fsSL https://Durar.ai/install.sh | bash
+```
+
+Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`.
+
+## Alternative: manual npm, pnpm, or bun
+
+```bash
+npm i -g Durar@latest
+```
+
+```bash
+pnpm add -g Durar@latest
+```
+
+```bash
+bun add -g Durar@latest
+```
+
+## Auto-updater
+
+The auto-updater is off by default. Enable it in `~/.Durar/Durar.json`:
+
+```json5
+{
+  update: {
+    channel: "stable",
+    auto: {
+      enabled: true,
+      stableDelayHours: 6,
+      stableJitterHours: 12,
+      betaCheckIntervalHours: 1,
+    },
+  },
+}
+```
+
+| Channel  | Behavior                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------- |
+| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
+| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
+| `dev`    | No automatic apply. Use `Durar update` manually.                                                           |
+
+The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
+
+## After updating
+
+<Steps>
+
+### Run doctor
+
+```bash
+Durar doctor
+```
+
+Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
+
+### Restart the gateway
+
+```bash
+Durar gateway restart
+```
+
+### Verify
+
+```bash
+Durar health
+```
+
+</Steps>
+
+## Rollback
+
+### Pin a version (npm)
+
+```bash
+npm i -g Durar@<version>
+Durar doctor
+Durar gateway restart
+```
+
+Tip: `npm view Durar version` shows the current published version.
+
+### Pin a commit (source)
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+pnpm install && pnpm build
+Durar gateway restart
+```
+
+To return to latest: `git checkout main && git pull`.
+
+## If you are stuck
+
+- Run `Durar doctor` again and read the output carefully.
+- Check: [Troubleshooting](/gateway/troubleshooting)
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
+
+## Related
+
+- [Install Overview](/install) — all installation methods
+- [Doctor](/gateway/doctor) — health checks after updates
+- [Migrating](/install/migrating) — major version migration guides