nodmix 2026.5.25

package/docs/install/podman.md

@@ -0,0 +1,210 @@
+---
+summary: "Run Nodmix in a rootless Podman container"
+read_when:
+  - You want a containerized gateway with Podman instead of Docker
+title: "Podman"
+---
+
+Run the Nodmix Gateway in a rootless Podman container, managed by your current non-root user.
+
+The intended model is:
+
+- Podman runs the gateway container.
+- Your host `nodmix` CLI is the control plane.
+- Persistent state lives on the host under `~/.nodmix` by default.
+- Day-to-day management uses `nodmix --container <name> ...` instead of `sudo -u nodmix`, `podman exec`, or a separate service user.
+
+## Prerequisites
+
+- **Podman** in rootless mode
+- **Nodmix CLI** installed on the host
+- **Optional:** `systemd --user` if you want Quadlet-managed auto-start
+- **Optional:** `sudo` only if you want `loginctl enable-linger "$(whoami)"` for boot persistence on a headless host
+
+## Quick start
+
+<Steps>
+  <Step title="One-time setup">
+    From the repo root, run `./scripts/podman/setup.sh`.
+  </Step>
+
+  <Step title="Start the Gateway container">
+    Start the container with `./scripts/run-nodmix-podman.sh launch`.
+  </Step>
+
+  <Step title="Run onboarding inside the container">
+    Run `./scripts/run-nodmix-podman.sh launch setup`, then open `http://127.0.0.1:18789/`.
+  </Step>
+
+  <Step title="Manage the running container from the host CLI">
+    Set `NODMIX_CONTAINER=nodmix`, then use normal `nodmix` commands from the host.
+  </Step>
+</Steps>
+
+Setup details:
+
+- `./scripts/podman/setup.sh` builds `nodmix:local` in your rootless Podman store by default, or uses `NODMIX_IMAGE` / `NODMIX_PODMAN_IMAGE` if you set one.
+- It creates `~/.nodmix/nodmix.json` with `gateway.mode: "local"` if missing.
+- It creates `~/.nodmix/.env` with `NODMIX_GATEWAY_TOKEN` if missing.
+- For manual launches, the helper reads only a small allowlist of Podman-related keys from `~/.nodmix/.env` and passes explicit runtime env vars to the container; it does not hand the full env file to Podman.
+
+Quadlet-managed setup:
+
+```bash
+./scripts/podman/setup.sh --quadlet
+```
+
+Quadlet is a Linux-only option because it depends on systemd user services.
+
+You can also set `NODMIX_PODMAN_QUADLET=1`.
+
+Optional build/setup env vars:
+
+- `NODMIX_IMAGE` or `NODMIX_PODMAN_IMAGE` -- use an existing/pulled image instead of building `nodmix:local`
+- `NODMIX_IMAGE_APT_PACKAGES` -- install extra apt packages during image build (also accepts legacy `NODMIX_DOCKER_APT_PACKAGES`)
+- `NODMIX_IMAGE_PIP_PACKAGES` -- install extra Python packages during image build; pin versions and use only package indexes you trust
+- `NODMIX_EXTENSIONS` -- pre-install plugin dependencies at build time
+- `NODMIX_INSTALL_BROWSER` -- pre-install Chromium and Xvfb for browser automation (set to `1` to enable)
+
+Container start:
+
+```bash
+./scripts/run-nodmix-podman.sh launch
+```
+
+The script starts the container as your current uid/gid with `--userns=keep-id` and bind-mounts your Nodmix state into the container.
+
+Onboarding:
+
+```bash
+./scripts/run-nodmix-podman.sh launch setup
+```
+
+Then open `http://127.0.0.1:18789/` and use the token from `~/.nodmix/.env`.
+
+Host CLI default:
+
+```bash
+export NODMIX_CONTAINER=nodmix
+```
+
+Then commands such as these will run inside that container automatically:
+
+```bash
+nodmix dashboard --no-open
+nodmix gateway status --deep   # includes extra service scan
+nodmix doctor
+nodmix channels login
+```
+
+On macOS, Podman machine may make the browser appear non-local to the gateway.
+If the Control UI reports device-auth errors after launch, use the Tailscale guidance in
+[Podman and Tailscale](#podman--tailscale).
+
+<a id="podman--tailscale"></a>
+
+## Podman and Tailscale
+
+For HTTPS or remote browser access, follow the main Tailscale docs.
+
+Podman-specific note:
+
+- Keep the Podman publish host at `127.0.0.1`.
+- Prefer host-managed `tailscale serve` over `nodmix gateway --tailscale serve`.
+- On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.
+
+See:
+
+- [Tailscale](/gateway/tailscale)
+- [Control UI](/web/control-ui)
+
+## Systemd (Quadlet, optional)
+
+If you ran `./scripts/podman/setup.sh --quadlet`, setup installs a Quadlet file at:
+
+```bash
+~/.config/containers/systemd/nodmix.container
+```
+
+Useful commands:
+
+- **Start:** `systemctl --user start nodmix.service`
+- **Stop:** `systemctl --user stop nodmix.service`
+- **Status:** `systemctl --user status nodmix.service`
+- **Logs:** `journalctl --user -u nodmix.service -f`
+
+After editing the Quadlet file:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart nodmix.service
+```
+
+For boot persistence on SSH/headless hosts, enable lingering for your current user:
+
+```bash
+sudo loginctl enable-linger "$(whoami)"
+```
+
+## Config, env, and storage
+
+- **Config dir:** `~/.nodmix`
+- **Workspace dir:** `~/.nodmix/workspace`
+- **Token file:** `~/.nodmix/.env`
+- **Launch helper:** `./scripts/run-nodmix-podman.sh`
+
+The launch script and Quadlet bind-mount host state into the container:
+
+- `NODMIX_CONFIG_DIR` -> `/home/node/.nodmix`
+- `NODMIX_WORKSPACE_DIR` -> `/home/node/.nodmix/workspace`
+
+By default those are host directories, not anonymous container state, so
+`nodmix.json`, per-agent `auth-profiles.json`, channel/provider state,
+sessions, and workspace survive container replacement.
+The Podman setup also seeds `gateway.controlUi.allowedOrigins` for `127.0.0.1` and `localhost` on the published gateway port so the local dashboard works with the container's non-loopback bind.
+
+Useful env vars for the manual launcher:
+
+- `NODMIX_PODMAN_CONTAINER` -- container name (`nodmix` by default)
+- `NODMIX_PODMAN_IMAGE` / `NODMIX_IMAGE` -- image to run
+- `NODMIX_PODMAN_GATEWAY_HOST_PORT` -- host port mapped to container `18789`
+- `NODMIX_PODMAN_BRIDGE_HOST_PORT` -- host port mapped to container `18790`
+- `NODMIX_PODMAN_PUBLISH_HOST` -- host interface for published ports; default is `127.0.0.1`
+- `NODMIX_GATEWAY_BIND` -- gateway bind mode inside the container; default is `lan`
+- `NODMIX_PODMAN_USERNS` -- `keep-id` (default), `auto`, or `host`
+
+The manual launcher reads `~/.nodmix/.env` before finalizing container/image defaults, so you can persist these there.
+
+If you use a non-default `NODMIX_CONFIG_DIR` or `NODMIX_WORKSPACE_DIR`, set the same variables for both `./scripts/podman/setup.sh` and later `./scripts/run-nodmix-podman.sh launch` commands. The repo-local launcher does not persist custom path overrides across shells.
+
+Quadlet note:
+
+- The generated Quadlet service intentionally keeps a fixed, hardened default shape: `127.0.0.1` published ports, `--bind lan` inside the container, and `keep-id` user namespace.
+- It pins `NODMIX_NO_RESPAWN=1`, `Restart=on-failure`, and `TimeoutStartSec=300`.
+- It publishes both `127.0.0.1:18789:18789` (gateway) and `127.0.0.1:18790:18790` (bridge).
+- It reads `~/.nodmix/.env` as a runtime `EnvironmentFile` for values such as `NODMIX_GATEWAY_TOKEN`, but it does not consume the manual launcher's Podman-specific override allowlist.
+- If you need custom publish ports, publish host, or other container-run flags, use the manual launcher or edit `~/.config/containers/systemd/nodmix.container` directly, then reload and restart the service.
+
+## Useful commands
+
+- **Container logs:** `podman logs -f nodmix`
+- **Stop container:** `podman stop nodmix`
+- **Remove container:** `podman rm -f nodmix`
+- **Open dashboard URL from host CLI:** `nodmix dashboard --no-open`
+- **Health/status via host CLI:** `nodmix gateway status --deep` (RPC probe + extra
+  service scan)
+
+## Troubleshooting
+
+- **Permission denied (EACCES) on config or workspace:** The container runs with `--userns=keep-id` and `--user <your uid>:<your gid>` by default. Ensure the host config/workspace paths are owned by your current user.
+- **Gateway start blocked (missing `gateway.mode=local`):** Ensure `~/.nodmix/nodmix.json` exists and sets `gateway.mode="local"`. `scripts/podman/setup.sh` creates this if missing.
+- **Container CLI commands hit the wrong target:** Use `nodmix --container <name> ...` explicitly, or export `NODMIX_CONTAINER=<name>` in your shell.
+- **`nodmix update` fails with `--container`:** Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
+- **Quadlet service does not start:** Run `systemctl --user daemon-reload`, then `systemctl --user start nodmix.service`. On headless systems you may also need `sudo loginctl enable-linger "$(whoami)"`.
+- **SELinux blocks bind mounts:** Leave the default mount behavior alone; the launcher auto-adds `:Z` on Linux when SELinux is enforcing or permissive.
+
+## Related
+
+- [Docker](/install/docker)
+- [Gateway background process](/gateway/background-process)
+- [Gateway troubleshooting](/gateway/troubleshooting)

package/docs/install/railway.mdx

@@ -0,0 +1,92 @@
+---
+summary: "Deploy Nodmix on Railway with one-click template"
+read_when:
+  - Deploying Nodmix to Railway
+  - You want a one-click cloud deploy with browser-based Control UI
+title: "Railway"
+---
+
+# Railway
+
+Deploy Nodmix on Railway with a one-click template and access it through the web Control UI.
+This is the easiest "no terminal on the server" path: Railway runs the Gateway for you.
+
+## Quick checklist (new users)
+
+1. Click **Deploy on Railway** (below).
+2. Add a **Volume** mounted at `/data`.
+3. Set the required **Variables** (at least `NODMIX_GATEWAY_PORT` and `NODMIX_GATEWAY_TOKEN`).
+4. Enable **HTTP Proxy** on port `8080`.
+5. Open `https://<your-railway-domain>/nodmix` and connect using the configured shared secret. This template uses `NODMIX_GATEWAY_TOKEN` by default; if you replace it with password auth, use that password instead.
+
+## One-click deploy
+
+<a href="https://railway.com/deploy/clawdbot-railway-template" target="_blank" rel="noreferrer">
+  Deploy on Railway
+</a>
+
+After deploy, find your public URL in **Railway → your service → Settings → Domains**.
+
+Railway will either:
+
+- give you a generated domain (often `https://<something>.up.railway.app`), or
+- use your custom domain if you attached one.
+
+Then open:
+
+- `https://<your-railway-domain>/nodmix` — Control UI
+
+## What you get
+
+- Hosted Nodmix Gateway + Control UI
+- Persistent storage via Railway Volume (`/data`) so `nodmix.json`,
+  per-agent `auth-profiles.json`, channel/provider state, sessions, and
+  workspace survive redeploys
+
+## Required Railway settings
+
+### Public Networking
+
+Enable **HTTP Proxy** for the service.
+
+- Port: `8080`
+
+### Volume (required)
+
+Attach a volume mounted at:
+
+- `/data`
+
+### Variables
+
+Set these variables on the service:
+
+- `NODMIX_GATEWAY_PORT=8080` (required — must match the port in Public Networking)
+- `NODMIX_GATEWAY_TOKEN` (required; treat as an admin secret)
+- `NODMIX_STATE_DIR=/data/.nodmix` (recommended)
+- `NODMIX_WORKSPACE_DIR=/data/workspace` (recommended)
+
+## Connect a channel
+
+Use the Control UI at `/nodmix` or run `nodmix onboard` via Railway's shell for channel setup instructions:
+
+- [Telegram](/channels/telegram) (fastest — just a bot token)
+- [Discord](/channels/discord)
+- [All channels](/channels)
+
+## Backups & migration
+
+Export your state, config, auth profiles, and workspace:
+
+```bash
+nodmix backup create
+```
+
+This creates a portable backup archive with Nodmix state plus any configured
+workspace. See [Backup](/cli/backup) for details.
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep Nodmix up to date: [Updating](/install/updating)

package/docs/install/raspberry-pi.md

@@ -0,0 +1,234 @@
+---
+summary: "Host Nodmix on a Raspberry Pi for always-on self-hosting"
+read_when:
+  - Setting up Nodmix on a Raspberry Pi
+  - Running Nodmix on ARM devices
+  - Building a cheap always-on personal AI
+title: "Raspberry Pi"
+---
+
+Run a persistent, always-on Nodmix 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 — typical hardware cost is **$35–80 one-time**, no monthly fees.
+
+## Hardware compatibility
+
+| Pi model    | RAM    | Works? | Notes                               |
+| ----------- | ------ | ------ | ----------------------------------- |
+| Pi 5        | 4/8 GB | Best   | Fastest, recommended.               |
+| Pi 4        | 4 GB   | Good   | Sweet spot for most users.          |
+| Pi 4        | 2 GB   | OK     | Add swap.                           |
+| Pi 4        | 1 GB   | Tight  | Possible with swap, minimal config. |
+| Pi 3B+      | 1 GB   | Slow   | Works but sluggish.                 |
+| Pi Zero 2 W | 512 MB | No     | Not recommended.                    |
+
+**Minimum:** 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS.
+**Recommended:** 2 GB+ RAM, 16 GB+ SD card (or USB SSD), Ethernet.
+
+## 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 Nodmix">
+    ```bash
+    curl -fsSL https://nodmix.ai/install.sh | bash
+    ```
+  </Step>
+
+  <Step title="Run onboarding">
+    ```bash
+    nodmix 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
+    nodmix status
+    systemctl --user status nodmix-gateway.service
+    journalctl --user -u nodmix-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 'nodmix 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/nodmix-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
+export NODE_COMPILE_CACHE=/var/tmp/nodmix-compile-cache
+mkdir -p /var/tmp/nodmix-compile-cache
+export NODMIX_NO_RESPAWN=1
+EOF
+source ~/.bashrc
+```
+
+`NODMIX_NO_RESPAWN=1` keeps routine Gateway restarts in-process, which avoids extra process handoffs and keeps PID tracking simple on small hosts.
+
+**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
+```
+
+**systemd drop-in for stable restarts** -- If this Pi is mostly running Nodmix, add a service drop-in:
+
+```bash
+systemctl --user edit nodmix-gateway.service
+```
+
+```ini
+[Service]
+Environment=NODMIX_NO_RESPAWN=1
+Environment=NODE_COMPILE_CACHE=/var/tmp/nodmix-compile-cache
+Restart=always
+RestartSec=2
+TimeoutStartSec=90
+```
+
+Then `systemctl --user daemon-reload && systemctl --user restart nodmix-gateway.service`. On a headless Pi, also enable lingering once so the user service survives logout: `sudo loginctl enable-linger "$(whoami)"`.
+
+## Recommended model setup
+
+Since the Pi only runs the gateway, use cloud-hosted API models:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4-6",
+        "fallbacks": ["openai/gpt-5.4-mini"]
+      }
+    }
+  }
+}
+```
+
+Do not run local LLMs on a Pi — even small models are too slow to be useful. Let Claude or GPT do the model work.
+
+## ARM binary notes
+
+Most Nodmix features work on ARM64 without changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that occasionally lack ARM builds are typically optional Go/Rust CLI tools shipped by skills. Verify a missing binary's release page for `linux-arm64` / `aarch64` artifacts before falling back to building from source.
+
+## Persistence and backups
+
+Nodmix state lives under:
+
+- `~/.nodmix/` — `nodmix.json`, per-agent `auth-profiles.json`, channel/provider state, sessions.
+- `~/.nodmix/workspace/` — agent workspace (SOUL.md, memory, artifacts).
+
+These survive reboots. Take a portable snapshot with:
+
+```bash
+nodmix backup create
+```
+
+If you keep these on an SSD, both performance and longevity improve over the SD card.
+
+## 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 nodmix-gateway.service --no-pager -n 100` and run `nodmix 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 Nodmix up to date
+
+## Related
+
+- [Install overview](/install)
+- [Linux server](/vps)
+- [Platforms](/platforms)

package/docs/install/render.mdx

@@ -0,0 +1,167 @@
+---
+summary: "Deploy Nodmix on Render with Infrastructure-as-Code"
+read_when:
+  - Deploying Nodmix to Render
+  - You want a declarative cloud deploy with Render Blueprints
+title: "Render"
+---
+
+# Render
+
+Deploy Nodmix 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/nodmix/nodmix)
+
+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 Nodmix:
+
+```yaml
+services:
+  - type: web
+    name: nodmix
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: NODMIX_GATEWAY_PORT
+        value: "8080"
+      - key: NODMIX_STATE_DIR
+        value: /data/.nodmix
+      - key: NODMIX_WORKSPACE_DIR
+        value: /data/workspace
+      - key: NODMIX_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: nodmix-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 Nodmix 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
+`NODMIX_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 Nodmix repository, Render will not auto-deploy your Nodmix. 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 Nodmix, 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
+nodmix backup create
+```
+
+This creates a portable backup archive with Nodmix 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 `NODMIX_GATEWAY_TOKEN` — verify it is set in **Dashboard → Environment**
+- Port mismatch — ensure `NODMIX_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 `nodmix 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 Nodmix up to date: [Updating](/install/updating)