nodmix 2026.5.25

package/docs/install/clawdock.md

@@ -0,0 +1,112 @@
+---
+summary: "ClawDock shell helpers for Docker-based Nodmix installs"
+read_when:
+  - You run Nodmix with Docker often and want shorter day-to-day commands
+  - You want a helper layer for dashboard, logs, token setup, and pairing flows
+title: "ClawDock"
+---
+
+ClawDock is a small shell-helper layer for Docker-based Nodmix installs.
+
+It gives you short commands like `clawdock-start`, `clawdock-dashboard`, and `clawdock-fix-token` instead of longer `docker compose ...` invocations.
+
+If you have not set up Docker yet, start with [Docker](/install/docker).
+
+## Install
+
+Use the canonical helper path:
+
+```bash
+mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/nodmix/nodmix/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
+echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
+```
+
+If you previously installed ClawDock from `scripts/shell-helpers/clawdock-helpers.sh`, reinstall from the new `scripts/clawdock/clawdock-helpers.sh` path. The old raw GitHub path was removed.
+
+## What you get
+
+### Basic operations
+
+| Command            | Description            |
+| ------------------ | ---------------------- |
+| `clawdock-start`   | Start the gateway      |
+| `clawdock-stop`    | Stop the gateway       |
+| `clawdock-restart` | Restart the gateway    |
+| `clawdock-status`  | Check container status |
+| `clawdock-logs`    | Follow gateway logs    |
+
+### Container access
+
+| Command                   | Description                                   |
+| ------------------------- | --------------------------------------------- |
+| `clawdock-shell`          | Open a shell inside the gateway container     |
+| `clawdock-cli <command>`  | Run Nodmix CLI commands in Docker           |
+| `clawdock-exec <command>` | Execute an arbitrary command in the container |
+
+### Web UI and pairing
+
+| Command                 | Description                  |
+| ----------------------- | ---------------------------- |
+| `clawdock-dashboard`    | Open the Control UI URL      |
+| `clawdock-devices`      | List pending device pairings |
+| `clawdock-approve <id>` | Approve a pairing request    |
+
+### Setup and maintenance
+
+| Command              | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `clawdock-fix-token` | Configure the gateway token inside the container |
+| `clawdock-update`    | Pull, rebuild, and restart                       |
+| `clawdock-rebuild`   | Rebuild the Docker image only                    |
+| `clawdock-clean`     | Remove containers and volumes                    |
+
+### Utilities
+
+| Command                | Description                             |
+| ---------------------- | --------------------------------------- |
+| `clawdock-health`      | Run a gateway health check              |
+| `clawdock-token`       | Print the gateway token                 |
+| `clawdock-cd`          | Jump to the Nodmix project directory  |
+| `clawdock-config`      | Open `~/.nodmix`                      |
+| `clawdock-show-config` | Print config files with redacted values |
+| `clawdock-workspace`   | Open the workspace directory            |
+
+## First-time flow
+
+```bash
+clawdock-start
+clawdock-fix-token
+clawdock-dashboard
+```
+
+If the browser says pairing is required:
+
+```bash
+clawdock-devices
+clawdock-approve <request-id>
+```
+
+## Config and secrets
+
+ClawDock works with the same Docker config split described in [Docker](/install/docker):
+
+- `<project>/.env` for Docker-specific values like image name, ports, and the gateway token
+- `~/.nodmix/.env` for env-backed provider keys and bot tokens
+- `~/.nodmix/agents/<agentId>/agent/auth-profiles.json` for stored provider OAuth/API-key auth
+- `~/.nodmix/nodmix.json` for behavior config
+
+Use `clawdock-show-config` when you want to inspect the `.env` files and `nodmix.json` quickly. It redacts `.env` values in its printed output.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Docker" href="/install/docker" icon="docker">
+    Canonical Docker install for Nodmix.
+  </Card>
+  <Card title="Docker VM runtime" href="/install/docker-vm-runtime" icon="cube">
+    Docker-managed VM runtime for hardened isolation.
+  </Card>
+  <Card title="Updating" href="/install/updating" icon="arrow-up-right-from-square">
+    Updating the Nodmix package and managed services.
+  </Card>
+</CardGroup>

package/docs/install/development-channels.md

@@ -0,0 +1,135 @@
+---
+summary: "Stable, beta, and dev channels: semantics, switching, pinning, and tagging"
+read_when:
+  - You want to switch between stable/beta/dev
+  - You want to pin a specific version, tag, or SHA
+  - You are tagging or publishing prereleases
+title: "Release channels"
+sidebarTitle: "Release Channels"
+---
+
+Nodmix ships three update channels:
+
+- **stable**: npm dist-tag `latest`. Recommended for most users.
+- **beta**: npm dist-tag `beta` when it is current; if beta is missing or older than
+  the latest stable release, the update flow falls back to `latest`.
+- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
+  The `main` branch is for experimentation and active development. It may contain
+  incomplete features or breaking changes. Do not use it for production gateways.
+
+We usually ship stable builds to **beta** first, test them there, then run an
+explicit promotion step that moves the vetted build to `latest` without
+changing the version number. Maintainers can also publish a stable release
+directly to `latest` when needed. Dist-tags are the source of truth for npm
+installs.
+
+## Switching channels
+
+```bash
+nodmix update --channel stable
+nodmix update --channel beta
+nodmix update --channel dev
+```
+
+`--channel` persists your choice in config (`update.channel`) and aligns the
+install method:
+
+- **`stable`** (package installs): updates via npm dist-tag `latest`.
+- **`beta`** (package installs): prefers npm dist-tag `beta`, but falls back to
+  `latest` when `beta` is missing or older than the current stable tag.
+- **`stable`** (git installs): checks out the latest stable git tag.
+- **`beta`** (git installs): prefers the latest beta git tag, but falls back to
+  the latest stable git tag when beta is missing or older.
+- **`dev`**: ensures a git checkout (default `~/nodmix`, override with
+  `NODMIX_GIT_DIR`), switches to `main`, rebases on upstream, builds, and
+  installs the global CLI from that checkout.
+
+<Tip>
+If you want stable and dev in parallel, keep two clones and point your gateway at the stable one.
+</Tip>
+
+## One-off version or tag targeting
+
+Use `--tag` to target a specific dist-tag, version, or package spec for a single
+update **without** changing your persisted channel:
+
+```bash
+# Install a specific version
+nodmix update --tag 2026.4.1-beta.1
+
+# Install from the beta dist-tag (one-off, does not persist)
+nodmix update --tag beta
+
+# Install from GitHub main branch (npm tarball)
+nodmix update --tag main
+
+# Install a specific npm package spec
+nodmix update --tag nodmix@2026.4.1-beta.1
+```
+
+Notes:
+
+- `--tag` applies to **package (npm) installs only**. Git installs ignore it.
+- The tag is not persisted. Your next `nodmix update` uses your configured
+  channel as usual.
+- Downgrade protection: if the target version is older than your current version,
+  Nodmix prompts for confirmation (skip with `--yes`).
+- `--channel beta` is different from `--tag beta`: the channel flow can fall back
+  to stable/latest when beta is missing or older, while `--tag beta` targets the
+  raw `beta` dist-tag for that one run.
+
+## Dry run
+
+Preview what `nodmix update` would do without making changes:
+
+```bash
+nodmix update --dry-run
+nodmix update --channel beta --dry-run
+nodmix update --tag 2026.4.1-beta.1 --dry-run
+nodmix update --dry-run --json
+```
+
+The dry run shows the effective channel, target version, planned actions, and
+whether a downgrade confirmation would be required.
+
+## Plugins and channels
+
+When you switch channels with `nodmix update`, Nodmix also syncs plugin
+sources:
+
+- `dev` prefers bundled plugins from the git checkout.
+- `stable` and `beta` restore npm-installed plugin packages.
+- npm-installed plugins are updated after the core update completes.
+
+## Checking current status
+
+```bash
+nodmix update status
+```
+
+Shows the active channel, install kind (git or package), current version, and
+source (config, git tag, git branch, or default).
+
+## Tagging best practices
+
+- Tag releases you want git checkouts to land on (`vYYYY.M.D` for stable,
+  `vYYYY.M.D-beta.N` for beta).
+- `vYYYY.M.D.beta.N` is also recognized for compatibility, but prefer `-beta.N`.
+- Legacy `vYYYY.M.D-<patch>` tags are still recognized as stable (non-beta).
+- Keep tags immutable: never move or reuse a tag.
+- npm dist-tags remain the source of truth for npm installs:
+  - `latest` -> stable
+  - `beta` -> candidate build or beta-first stable build
+  - `dev` -> main snapshot (optional)
+
+## macOS app availability
+
+Beta and dev builds may **not** include a macOS app release. That is OK:
+
+- The git tag and npm dist-tag can still be published.
+- Call out "no macOS build for this beta" in release notes or changelog.
+
+## Related
+
+- [Updating](/install/updating)
+- [Installer internals](/install/installer)

package/docs/install/digitalocean.md

@@ -0,0 +1,174 @@
+---
+summary: "Host Nodmix on a DigitalOcean Droplet"
+read_when:
+  - Setting up Nodmix on DigitalOcean
+  - Looking for a simple paid VPS for Nodmix
+title: "DigitalOcean"
+---
+
+Run a persistent Nodmix Gateway on a DigitalOcean Droplet (~$6/month for the 1 GB Basic plan).
+
+DigitalOcean is the simplest paid VPS path. If you prefer cheaper or free options:
+
+- [Hetzner](/install/hetzner) — €3.79/mo, more cores/RAM per dollar.
+- [Oracle Cloud](/install/oracle) — Always Free ARM (up to 4 OCPU, 24 GB RAM), but signup can be finicky and ARM-only.
+
+## Prerequisites
+
+- DigitalOcean account ([signup](https://cloud.digitalocean.com/registrations/new))
+- SSH key pair (or willingness to use password auth)
+- About 20 minutes
+
+## Setup
+
+<Steps>
+  <Step title="Create a Droplet">
+    <Warning>
+    Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults.
+    </Warning>
+
+    1. Log into [DigitalOcean](https://cloud.digitalocean.com/).
+    2. Click **Create > Droplets**.
+    3. Choose:
+       - **Region:** Closest to you
+       - **Image:** Ubuntu 24.04 LTS
+       - **Size:** Basic, Regular, 1 vCPU / 1 GB RAM / 25 GB SSD
+       - **Authentication:** SSH key (recommended) or password
+    4. Click **Create Droplet** and note the IP address.
+
+  </Step>
+
+  <Step title="Connect and install">
+    ```bash
+    ssh root@YOUR_DROPLET_IP
+
+    apt update && apt upgrade -y
+
+    # Install Node.js 24
+    curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
+    apt install -y nodejs
+
+    # Install Nodmix
+    curl -fsSL https://nodmix.ai/install.sh | bash
+
+    # Create the non-root user that will own Nodmix state and services.
+    adduser nodmix
+    usermod -aG sudo nodmix
+    loginctl enable-linger nodmix
+
+    su - nodmix
+    nodmix --version
+    ```
+
+    Use the root shell only for system bootstrap. Run Nodmix commands as the non-root `nodmix` user so state lives under `/home/nodmix/.nodmix/` and the Gateway installs as that user's systemd service.
+
+  </Step>
+
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --install-daemon
+    ```
+
+    The wizard walks you through model auth, channel setup, gateway token generation, and daemon installation (systemd).
+
+  </Step>
+
+  <Step title="Add swap (recommended for 1 GB Droplets)">
+    ```bash
+    fallocate -l 2G /swapfile
+    chmod 600 /swapfile
+    mkswap /swapfile
+    swapon /swapfile
+    echo '/swapfile none swap sw 0 0' >> /etc/fstab
+    ```
+  </Step>
+
+  <Step title="Verify the gateway">
+    ```bash
+    nodmix status
+    systemctl --user status nodmix-gateway.service
+    journalctl --user -u nodmix-gateway.service -f
+    ```
+  </Step>
+
+  <Step title="Access the Control UI">
+    The gateway binds to loopback by default. Pick one of these options.
+
+    **Option A: SSH tunnel (simplest)**
+
+    ```bash
+    # From your local machine
+    ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
+    ```
+
+    Then open `http://localhost:18789`.
+
+    **Option B: Tailscale Serve**
+
+    ```bash
+    curl -fsSL https://tailscale.com/install.sh | sudo sh
+    sudo tailscale up
+    nodmix config set gateway.tailscale.mode serve
+    nodmix gateway restart
+    ```
+
+    Then open `https://<magicdns>/` from any device on your tailnet.
+
+    Tailscale Serve authenticates Control UI and WebSocket traffic via tailnet identity headers, which assumes the gateway host itself is trusted. HTTP API endpoints follow the gateway's normal auth mode (token/password) regardless. To require explicit shared-secret credentials over Serve, set `gateway.auth.allowTailscale: false` and use `gateway.auth.mode: "token"` or `"password"`.
+
+    **Option C: Tailnet bind (no Serve)**
+
+    ```bash
+    nodmix config set gateway.bind tailnet
+    nodmix gateway restart
+    ```
+
+    Then open `http://<tailscale-ip>:18789` (token required).
+
+  </Step>
+</Steps>
+
+## Persistence and backups
+
+Nodmix state lives under:
+
+- `~/.nodmix/` — `nodmix.json`, per-agent `auth-profiles.json`, channel/provider state, and session data.
+- `~/.nodmix/workspace/` — the agent workspace (SOUL.md, memory, artifacts).
+
+These survive Droplet reboots. To take a portable snapshot:
+
+```bash
+nodmix backup create
+```
+
+DigitalOcean snapshots back the whole Droplet up; `nodmix backup create` is portable across hosts.
+
+## 1 GB RAM tips
+
+The $6 Droplet only has 1 GB RAM. To keep things smooth:
+
+- Make sure the swap step above is in `/etc/fstab` so it survives reboots.
+- Prefer API-based models (Claude, GPT) over local ones — local LLM inference does not fit in 1 GB.
+- Set `agents.defaults.model.primary` to a smaller model if you hit OOMs on large prompts.
+- Monitor with `free -h` and `htop`.
+
+## Troubleshooting
+
+**Gateway will not start** -- Run `nodmix doctor --non-interactive` and check logs with `journalctl --user -u nodmix-gateway.service -n 50`.
+
+**Port already in use** -- Run `lsof -i :18789` to find the process, then stop it.
+
+**Out of memory** -- Verify swap is active with `free -h`. If still hitting OOM, use API-based models (Claude, GPT) rather than local models, or upgrade to a 2 GB Droplet.
+
+## Next steps
+
+- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
+- [Gateway configuration](/gateway/configuration) -- all config options
+- [Updating](/install/updating) -- keep Nodmix up to date
+
+## Related
+
+- [Install overview](/install)
+- [Fly.io](/install/fly)
+- [Hetzner](/install/hetzner)
+- [VPS hosting](/vps)

package/docs/install/docker-vm-runtime.md

@@ -0,0 +1,154 @@
+---
+summary: "Shared Docker VM runtime steps for long-lived Nodmix Gateway hosts"
+read_when:
+  - You are deploying Nodmix on a cloud VM with Docker
+  - You need the shared binary bake, persistence, and update flow
+title: "Docker VM runtime"
+---
+
+Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.
+
+## Bake required binaries into the image
+
+Installing binaries inside a running container is a trap.
+Anything installed at runtime will be lost on restart.
+
+All external binaries required by skills must be installed at image build time.
+
+The examples below show three common binaries only:
+
+- `gog` (from `gogcli`) for Gmail access
+- `goplaces` for Google Places
+- `wacli` for WhatsApp
+
+These are examples, not a complete list.
+You may install as many binaries as needed using the same pattern.
+
+If you add new skills later that depend on additional binaries, you must:
+
+1. Update the Dockerfile
+2. Rebuild the image
+3. Restart the containers
+
+**Example Dockerfile**
+
+```dockerfile
+FROM node:24-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# Example binary 1: Gmail CLI (gogcli — installs as `gog`)
+# Copy the current Linux asset URL from https://github.com/steipete/gogcli/releases
+RUN curl -L https://github.com/steipete/gogcli/releases/latest/download/gogcli_linux_amd64.tar.gz \
+  | tar -xzO gog > /usr/local/bin/gog; \
+  chmod +x /usr/local/bin/gog
+
+# Example binary 2: Google Places CLI
+# Copy the current Linux asset URL from https://github.com/steipete/goplaces/releases
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_linux_amd64.tar.gz \
+  | tar -xzO goplaces > /usr/local/bin/goplaces; \
+  chmod +x /usr/local/bin/goplaces
+
+# Example binary 3: WhatsApp CLI
+# Copy the current Linux asset URL from https://github.com/steipete/wacli/releases
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli-linux-amd64.tar.gz \
+  | tar -xzO wacli > /usr/local/bin/wacli; \
+  chmod +x /usr/local/bin/wacli
+
+# Add more binaries below using the same pattern
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+<Note>
+The URLs above are examples. For ARM-based VMs, choose the `arm64` assets. For reproducible builds, pin versioned release URLs.
+</Note>
+
+## Build and launch
+
+```bash
+docker compose build
+docker compose up -d nodmix-gateway
+```
+
+If build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory.
+Use a larger machine class before retrying.
+
+Verify binaries:
+
+```bash
+docker compose exec nodmix-gateway which gog
+docker compose exec nodmix-gateway which goplaces
+docker compose exec nodmix-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+Verify Gateway:
+
+```bash
+docker compose logs -f nodmix-gateway
+```
+
+Expected output:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+## What persists where
+
+Nodmix runs in Docker, but Docker is not the source of truth.
+All long-lived state must survive restarts, rebuilds, and reboots.
+
+| Component           | Location                                               | Persistence mechanism  | Notes                                                         |
+| ------------------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------- |
+| Gateway config      | `/home/node/.nodmix/`                                | Host volume mount      | Includes `nodmix.json`, `.env`                              |
+| Model auth profiles | `/home/node/.nodmix/agents/`                         | Host volume mount      | `agents/<agentId>/agent/auth-profiles.json` (OAuth, API keys) |
+| Auth profile key    | `/home/node/.config/nodmix/`                         | Host volume mount      | Local encryption key for OAuth auth profile token material    |
+| Skill configs       | `/home/node/.nodmix/skills/`                         | Host volume mount      | Skill-level state                                             |
+| Agent workspace     | `/home/node/.nodmix/workspace/`                      | Host volume mount      | Code and agent artifacts                                      |
+| WhatsApp session    | `/home/node/.nodmix/`                                | Host volume mount      | Preserves QR login                                            |
+| Gmail keyring       | `/home/node/.nodmix/`                                | Host volume + password | Requires `GOG_KEYRING_PASSWORD`                               |
+| Plugin packages     | `/home/node/.nodmix/npm`, `/home/node/.nodmix/git` | Host volume mount      | Downloadable plugin package roots                             |
+| External binaries   | `/usr/local/bin/`                                      | Docker image           | Must be baked at build time                                   |
+| Node runtime        | Container filesystem                                   | Docker image           | Rebuilt every image build                                     |
+| OS packages         | Container filesystem                                   | Docker image           | Do not install at runtime                                     |
+| Docker container    | Ephemeral                                              | Restartable            | Safe to destroy                                               |
+
+## Updates
+
+To update Nodmix on the VM:
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```
+
+## Related
+
+- [Docker](/install/docker)
+- [Podman](/install/podman)
+- [ClawDock](/install/clawdock)