nodmix 2026.5.25

package/docs/install/migrating.md

@@ -0,0 +1,137 @@
+---
+summary: "Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades"
+read_when:
+  - You are moving Nodmix to a new laptop or server
+  - You are coming from another agent system and want to keep state
+  - You are upgrading an in-place plugin
+title: "Migration guide"
+---
+
+Nodmix supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.
+
+## Import from another agent system
+
+Use the bundled migration providers to bring instructions, MCP servers, skills, model config, and (opt-in) API keys into Nodmix. Plans are previewed before any change, secrets are redacted in reports, and apply is backed by a verified backup.
+
+<CardGroup cols={2}>
+  <Card title="Migrating from Claude" href="/install/migrating-claude" icon="brain">
+    Import Claude Code and Claude Desktop state, including `CLAUDE.md`, MCP servers, skills, and project commands.
+  </Card>
+  <Card title="Migrating from Hermes" href="/install/migrating-hermes" icon="feather">
+    Import Hermes config, providers, MCP servers, memory, skills, and supported `.env` keys.
+  </Card>
+</CardGroup>
+
+The CLI entry point is [`nodmix migrate`](/cli/migrate). Onboarding can also offer migration when it detects a known source (`nodmix onboard --flow import`).
+
+## Move Nodmix to a new machine
+
+Copy the **state directory** (`~/.nodmix/` by default) and your **workspace** to preserve:
+
+- **Config** — `nodmix.json` and all gateway settings.
+- **Auth** — per-agent `auth-profiles.json` (API keys plus OAuth), plus any channel or provider state under `credentials/`.
+- **Sessions** — conversation history and agent state.
+- **Channel state** — WhatsApp login, Telegram session, and similar.
+- **Workspace files** — `MEMORY.md`, `USER.md`, skills, and prompts.
+
+<Tip>
+Run `nodmix status` on the old machine to confirm your state directory path. Custom profiles use `~/.nodmix-<profile>/` or a path set via `NODMIX_STATE_DIR`.
+</Tip>
+
+### Migration steps
+
+<Steps>
+  <Step title="Stop the gateway and back up">
+    On the **old** machine, stop the gateway so files are not changing mid-copy, then archive:
+
+    ```bash
+    nodmix gateway stop
+    cd ~
+    tar -czf nodmix-state.tgz .nodmix
+    ```
+
+    If you use multiple profiles (for example `~/.nodmix-work`), archive each separately.
+
+  </Step>
+
+  <Step title="Install Nodmix on the new machine">
+    [Install](/install) the CLI (and Node if needed) on the new machine. It is fine if onboarding creates a fresh `~/.nodmix/`. You will overwrite it next.
+  </Step>
+
+  <Step title="Copy state directory and workspace">
+    Transfer the archive via `scp`, `rsync -a`, or an external drive, then extract:
+
+    ```bash
+    cd ~
+    tar -xzf nodmix-state.tgz
+    ```
+
+    Ensure hidden directories were included and file ownership matches the user that will run the gateway.
+
+  </Step>
+
+  <Step title="Run doctor and verify">
+    On the new machine, run [Doctor](/gateway/doctor) to apply config migrations and repair services:
+
+    ```bash
+    nodmix doctor
+    nodmix gateway restart
+    nodmix status
+    ```
+
+  </Step>
+</Steps>
+
+If Telegram or Discord uses the default env fallback (`TELEGRAM_BOT_TOKEN` or `DISCORD_BOT_TOKEN`), verify the migrated state-dir `.env` contains those keys without printing the secret values:
+
+```bash
+awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.nodmix/.env
+```
+
+`nodmix doctor` also warns when an enabled default Telegram or Discord account has no configured token and the matching env variable is unavailable to the doctor process.
+
+### Common pitfalls
+
+<AccordionGroup>
+  <Accordion title="Profile or state-dir mismatch">
+    If the old gateway used `--profile` or `NODMIX_STATE_DIR` and the new one does not, channels will appear logged out and sessions will be empty. Launch the gateway with the **same** profile or state-dir you migrated, then rerun `nodmix doctor`.
+  </Accordion>
+
+  <Accordion title="Copying only nodmix.json">
+    The config file alone is not enough. Model auth profiles live under `agents/<agentId>/agent/auth-profiles.json`, and channel and provider state lives under `credentials/`. Always migrate the **entire** state directory.
+  </Accordion>
+
+  <Accordion title="Permissions and ownership">
+    If you copied as root or switched users, the gateway may fail to read credentials. Ensure the state directory and workspace are owned by the user running the gateway.
+  </Accordion>
+
+  <Accordion title="Remote mode">
+    If your UI points at a **remote** gateway, the remote host owns sessions and workspace. Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-things-live-on-disk).
+  </Accordion>
+
+  <Accordion title="Secrets in backups">
+    The state directory contains auth profiles, channel credentials, and other provider state. Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.
+  </Accordion>
+</AccordionGroup>
+
+### Verification checklist
+
+On the new machine, confirm:
+
+- [ ] `nodmix status` shows the gateway running.
+- [ ] Channels are still connected (no re-pairing needed).
+- [ ] The dashboard opens and shows existing sessions.
+- [ ] Workspace files (memory, configs) are present.
+
+## Upgrade a plugin in place
+
+In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. Plugin-specific upgrade guides live alongside their channels:
+
+- [Matrix migration](/channels/matrix-migration): encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands.
+
+## Related
+
+- [`nodmix migrate`](/cli/migrate): CLI reference for cross-system imports.
+- [Install overview](/install): all installation methods.
+- [Doctor](/gateway/doctor): post-migration health check.
+- [Uninstall](/install/uninstall): removing Nodmix cleanly.

package/docs/install/nix.md

@@ -0,0 +1,112 @@
+---
+summary: "Install Nodmix declaratively with Nix"
+read_when:
+  - You want reproducible, rollback-able installs
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
+title: "Nix"
+---
+
+Install Nodmix declaratively with **[nix-nodmix](https://github.com/nodmix/nix-nodmix)** - the first-party, batteries-included Home Manager module.
+
+<Info>
+The [nix-nodmix](https://github.com/nodmix/nix-nodmix) repo is the source of truth for Nix installation. This page is a quick overview.
+</Info>
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) -- all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+## Quick start
+
+<Steps>
+  <Step title="Install Determinate Nix">
+    If Nix is not already installed, follow the [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer) instructions.
+  </Step>
+  <Step title="Create a local flake">
+    Use the agent-first template from the nix-nodmix repo:
+    ```bash
+    mkdir -p ~/code/nodmix-local
+    # Copy templates/agent-first/flake.nix from the nix-nodmix repo
+    ```
+  </Step>
+  <Step title="Configure secrets">
+    Set up your messaging bot token and model provider API key. Plain files at `~/.secrets/` work fine.
+  </Step>
+  <Step title="Fill in template placeholders and switch">
+    ```bash
+    home-manager switch
+    ```
+  </Step>
+  <Step title="Verify">
+    Confirm the launchd service is running and your bot responds to messages.
+  </Step>
+</Steps>
+
+See the [nix-nodmix README](https://github.com/nodmix/nix-nodmix) for full module options and examples.
+
+## Nix-mode runtime behavior
+
+When `NODMIX_NIX_MODE=1` is set (automatic with nix-nodmix), Nodmix enters a deterministic mode for Nix-managed installs. Other Nix packages can set the same mode; nix-nodmix is the first-party reference.
+
+You can also set it manually:
+
+```bash
+export NODMIX_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead:
+
+```bash
+defaults write ai.nodmix.mac nodmix.nixMode -bool true
+```
+
+### What changes in Nix mode
+
+- Auto-install and self-mutation flows are disabled
+- `nodmix.json` is treated as immutable. Startup-derived defaults stay runtime-only, and config writers such as setup, onboarding, mutating `nodmix update`, plugin install/update/uninstall/enable, `doctor --fix`, `doctor --generate-gateway-token`, and `nodmix config set` refuse to edit the file.
+- Agents should edit the Nix source instead. For nix-nodmix, use the agent-first [Quick Start](https://github.com/nodmix/nix-nodmix#quick-start) and set config under `programs.nodmix.config` or `instances.<name>.config`.
+- Missing dependencies surface Nix-specific remediation messages
+- UI surfaces a read-only Nix mode banner
+
+### Config and state paths
+
+Nodmix reads JSON5 config from `NODMIX_CONFIG_PATH` and stores mutable data in `NODMIX_STATE_DIR`. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.
+
+| Variable               | Default                                 |
+| ---------------------- | --------------------------------------- |
+| `NODMIX_HOME`        | `HOME` / `USERPROFILE` / `os.homedir()` |
+| `NODMIX_STATE_DIR`   | `~/.nodmix`                           |
+| `NODMIX_CONFIG_PATH` | `$NODMIX_STATE_DIR/nodmix.json`     |
+
+### Service PATH discovery
+
+The launchd/systemd gateway service auto-discovers Nix-profile binaries so
+plugins and tools that shell out to `nix`-installed executables work without
+manual PATH setup:
+
+- When `NIX_PROFILES` is set, every entry is added to the service PATH in
+  right-to-left precedence (matches Nix shell precedence - rightmost wins).
+- When `NIX_PROFILES` is unset, `~/.nix-profile/bin` is added as a fallback.
+
+This applies to both macOS launchd and Linux systemd service environments.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="nix-nodmix" href="https://github.com/nodmix/nix-nodmix" icon="arrow-up-right-from-square">
+    Source-of-truth Home Manager module and full setup guide.
+  </Card>
+  <Card title="Setup wizard" href="/start/wizard" icon="wand-magic-sparkles">
+    Non-Nix CLI setup walkthrough.
+  </Card>
+  <Card title="Docker" href="/install/docker" icon="docker">
+    Containerized setup as a non-Nix alternative.
+  </Card>
+  <Card title="Updating" href="/install/updating" icon="arrow-up-right-from-square">
+    Updating Home Manager-managed installs alongside the package.
+  </Card>
+</CardGroup>

package/docs/install/node.md

@@ -0,0 +1,142 @@
+---
+summary: "Install and configure Node.js for Nodmix - version requirements, install options, and PATH troubleshooting"
+title: "Node.js"
+read_when:
+  - "You need to install Node.js before installing Nodmix"
+  - "You installed Nodmix but `nodmix` is command not found"
+  - "npm install -g fails with permissions or PATH issues"
+---
+
+Nodmix requires **Node 22.19 or newer**. **Node 24 is the default and recommended runtime** for installs, CI, and release workflows. Node 22 remains supported via the active LTS line. The [installer script](/install#alternative-install-methods) will detect and install Node automatically - this page is for when you want to set up Node yourself and make sure everything is wired up correctly (versions, PATH, global installs).
+
+## Check your version
+
+```bash
+node -v
+```
+
+If this prints `v24.x.x` or higher, you're on the recommended default. If it prints `v22.19.x` or higher, you're on the supported Node 22 LTS path, but we still recommend upgrading to Node 24 when convenient. If Node isn't installed or the version is too old, pick an install method below.
+
+## Install Node
+
+<Tabs>
+  <Tab title="macOS">
+    **Homebrew** (recommended):
+
+    ```bash
+    brew install node
+    ```
+
+    Or download the macOS installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+  <Tab title="Linux">
+    **Ubuntu / Debian:**
+
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+    ```
+
+    **Fedora / RHEL:**
+
+    ```bash
+    sudo dnf install nodejs
+    ```
+
+    Or use a version manager (see below).
+
+  </Tab>
+  <Tab title="Windows">
+    **winget** (recommended):
+
+    ```powershell
+    winget install OpenJS.NodeJS.LTS
+    ```
+
+    **Chocolatey:**
+
+    ```powershell
+    choco install nodejs-lts
+    ```
+
+    Or download the Windows installer from [nodejs.org](https://nodejs.org/).
+
+  </Tab>
+</Tabs>
+
+<Accordion title="Using a version manager (nvm, fnm, mise, asdf)">
+  Version managers let you switch between Node versions easily. Popular options:
+
+- [**fnm**](https://github.com/Schniz/fnm) - fast, cross-platform
+- [**nvm**](https://github.com/nvm-sh/nvm) - widely used on macOS/Linux
+- [**mise**](https://mise.jdx.dev/) - polyglot (Node, Python, Ruby, etc.)
+
+Example with fnm:
+
+```bash
+fnm install 24
+fnm use 24
+```
+
+  <Warning>
+  Make sure your version manager is initialized in your shell startup file (`~/.zshrc` or `~/.bashrc`). If it isn't, `nodmix` may not be found in new terminal sessions because the PATH won't include Node's bin directory.
+  </Warning>
+</Accordion>
+
+## Troubleshooting
+
+### `nodmix: command not found`
+
+This almost always means npm's global bin directory isn't on your PATH.
+
+<Steps>
+  <Step title="Find your global npm prefix">
+    ```bash
+    npm prefix -g
+    ```
+  </Step>
+  <Step title="Check if it's on your PATH">
+    ```bash
+    echo "$PATH"
+    ```
+
+    Look for `<npm-prefix>/bin` (macOS/Linux) or `<npm-prefix>` (Windows) in the output.
+
+  </Step>
+  <Step title="Add it to your shell startup file">
+    <Tabs>
+      <Tab title="macOS / Linux">
+        Add to `~/.zshrc` or `~/.bashrc`:
+
+        ```bash
+        export PATH="$(npm prefix -g)/bin:$PATH"
+        ```
+
+        Then open a new terminal (or run `rehash` in zsh / `hash -r` in bash).
+      </Tab>
+      <Tab title="Windows">
+        Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables.
+      </Tab>
+    </Tabs>
+
+  </Step>
+</Steps>
+
+### Permission errors on `npm install -g` (Linux)
+
+If you see `EACCES` errors, switch npm's global prefix to a user-writable directory:
+
+```bash
+mkdir -p "$HOME/.npm-global"
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+Add the `export PATH=...` line to your `~/.bashrc` or `~/.zshrc` to make it permanent.
+
+## Related
+
+- [Install Overview](/install) - all installation methods
+- [Updating](/install/updating) - keeping Nodmix up to date
+- [Getting Started](/start/getting-started) - first steps after install

package/docs/install/northflank.mdx

@@ -0,0 +1,44 @@
+---
+summary: "Deploy Nodmix on Northflank with one-click template"
+read_when:
+  - Deploying Nodmix to Northflank
+  - You want a one-click cloud deploy with browser-based Control UI
+title: "Northflank"
+---
+
+# Northflank
+
+Deploy Nodmix on Northflank with a one-click template and access it through the web Control UI.
+This is the easiest "no terminal on the server" path: Northflank runs the Gateway for you.
+
+## How to get started
+
+1. Click [Deploy Nodmix](https://northflank.com/stacks/deploy-nodmix) to open the template.
+2. Create an [account on Northflank](https://app.northflank.com/signup) if you don't already have one.
+3. Click **Deploy Nodmix now**.
+4. Set the required environment variable: `NODMIX_GATEWAY_TOKEN` (use a strong random value).
+5. Click **Deploy stack** to build and run the Nodmix template.
+6. Wait for the deployment to complete, then click **View resources**.
+7. Open the Nodmix service.
+8. Open the public Nodmix URL at `/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.
+
+## What you get
+
+- Hosted Nodmix Gateway + Control UI
+- Persistent storage via Northflank Volume (`/data`) so `nodmix.json`,
+  per-agent `auth-profiles.json`, channel/provider state, sessions, and
+  workspace survive redeploys
+
+## Connect a channel
+
+Use the Control UI at `/nodmix` or run `nodmix onboard` via SSH for channel setup instructions:
+
+- [Telegram](/channels/telegram) (fastest — just a bot token)
+- [Discord](/channels/discord)
+- [All channels](/channels)
+
+## 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/oracle.md

@@ -0,0 +1,218 @@
+---
+summary: "Host Nodmix on Oracle Cloud's Always Free ARM tier"
+read_when:
+  - Setting up Nodmix on Oracle Cloud
+  - Looking for free VPS hosting for Nodmix
+  - Want 24/7 Nodmix on a small server
+title: "Oracle Cloud"
+---
+
+Run a persistent Nodmix Gateway on Oracle Cloud's **Always Free** ARM tier (up to 4 OCPU, 24 GB RAM, 200 GB storage) at no cost.
+
+## Prerequisites
+
+- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) -- see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues
+- Tailscale account (free at [tailscale.com](https://tailscale.com))
+- An SSH key pair
+- About 30 minutes
+
+## Setup
+
+<Steps>
+  <Step title="Create an OCI instance">
+    1. Log into [Oracle Cloud Console](https://cloud.oracle.com/).
+    2. Navigate to **Compute > Instances > Create Instance**.
+    3. Configure:
+       - **Name:** `nodmix`
+       - **Image:** Ubuntu 24.04 (aarch64)
+       - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
+       - **OCPUs:** 2 (or up to 4)
+       - **Memory:** 12 GB (or up to 24 GB)
+       - **Boot volume:** 50 GB (up to 200 GB free)
+       - **SSH key:** Add your public key
+    4. Click **Create** and note the public IP address.
+
+    <Tip>
+    If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.
+    </Tip>
+
+  </Step>
+
+  <Step title="Connect and update the system">
+    ```bash
+    ssh ubuntu@YOUR_PUBLIC_IP
+
+    sudo apt update && sudo apt upgrade -y
+    sudo apt install -y build-essential
+    ```
+
+    `build-essential` is required for ARM compilation of some dependencies.
+
+  </Step>
+
+  <Step title="Configure user and hostname">
+    ```bash
+    sudo hostnamectl set-hostname nodmix
+    sudo passwd ubuntu
+    sudo loginctl enable-linger ubuntu
+    ```
+
+    Enabling linger keeps user services running after logout.
+
+  </Step>
+
+  <Step title="Install Tailscale">
+    ```bash
+    curl -fsSL https://tailscale.com/install.sh | sh
+    sudo tailscale up --ssh --hostname=nodmix
+    ```
+
+    From now on, connect via Tailscale: `ssh ubuntu@nodmix`.
+
+  </Step>
+
+  <Step title="Install Nodmix">
+    ```bash
+    curl -fsSL https://nodmix.ai/install.sh | bash
+    source ~/.bashrc
+    ```
+
+    When prompted "How do you want to hatch your bot?", select **Do this later**.
+
+  </Step>
+
+  <Step title="Configure the gateway">
+    Use token auth with Tailscale Serve for secure remote access.
+
+    ```bash
+    nodmix config set gateway.bind loopback
+    nodmix config set gateway.auth.mode token
+    nodmix doctor --generate-gateway-token
+    nodmix config set gateway.tailscale.mode serve
+    nodmix config set gateway.trustedProxies '["127.0.0.1"]'
+
+    systemctl --user restart nodmix-gateway.service
+    ```
+
+    `gateway.trustedProxies=["127.0.0.1"]` here is only for the local Tailscale Serve proxy's forwarded-IP/local-client handling. It is **not** `gateway.auth.mode: "trusted-proxy"`. Diff viewer routes keep fail-closed behavior in this setup: raw `127.0.0.1` viewer requests without forwarded proxy headers can return `Diff not found`. Use `mode=file` / `mode=both` for attachments, or intentionally enable remote viewers and set `plugins.entries.diffs.config.viewerBaseUrl` (or pass a proxy `baseUrl`) if you need shareable viewer links.
+
+  </Step>
+
+  <Step title="Lock down VCN security">
+    Block all traffic except Tailscale at the network edge:
+
+    1. Go to **Networking > Virtual Cloud Networks** in the OCI Console.
+    2. Click your VCN, then **Security Lists > Default Security List**.
+    3. **Remove** all ingress rules except `0.0.0.0/0 UDP 41641` (Tailscale).
+    4. Keep default egress rules (allow all outbound).
+
+    This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. You can only connect via Tailscale from this point on.
+
+  </Step>
+
+  <Step title="Verify">
+    ```bash
+    nodmix --version
+    systemctl --user status nodmix-gateway.service
+    tailscale serve status
+    curl http://localhost:18789
+    ```
+
+    Access the Control UI from any device on your tailnet:
+
+    ```
+    https://nodmix.<tailnet-name>.ts.net/
+    ```
+
+    Replace `<tailnet-name>` with your tailnet name (visible in `tailscale status`).
+
+  </Step>
+</Steps>
+
+## Verify the security posture
+
+With the VCN locked down (only UDP 41641 open) and the Gateway bound to loopback, public traffic is blocked at the network edge and admin access is tailnet-only. That removes the need for several traditional VPS hardening steps:
+
+| Traditional step   | Needed?     | Why                                                                       |
+| ------------------ | ----------- | ------------------------------------------------------------------------- |
+| UFW firewall       | No          | The VCN blocks traffic before it reaches the instance.                    |
+| fail2ban           | No          | Port 22 is blocked at the VCN; no brute-force surface.                    |
+| sshd hardening     | No          | Tailscale SSH does not use sshd.                                          |
+| Disable root login | No          | Tailscale authenticates by tailnet identity, not system users.            |
+| SSH key-only auth  | No          | Same — tailnet identity replaces system SSH keys.                         |
+| IPv6 hardening     | Usually not | Depends on VCN/subnet settings; verify what is actually assigned/exposed. |
+
+Still recommended:
+
+- `chmod 700 ~/.nodmix` to restrict credential file permissions.
+- `nodmix security audit` for an Nodmix-specific posture check.
+- Regular `sudo apt update && sudo apt upgrade` for OS patches.
+- Review devices in the [Tailscale admin console](https://login.tailscale.com/admin) periodically.
+
+Quick verification commands:
+
+```bash
+# Confirm no public ports are listening
+sudo ss -tlnp | grep -v '127.0.0.1\|::1'
+
+# Verify Tailscale SSH is active
+tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"
+
+# Optional: disable sshd entirely once Tailscale SSH is confirmed working
+sudo systemctl disable --now ssh
+```
+
+## ARM notes
+
+The Always Free tier is ARM (`aarch64`). Most Nodmix features work fine; a small number of native binaries need ARM builds:
+
+- Node.js, Telegram, WhatsApp (Baileys): pure JavaScript, no issues.
+- Most npm packages with native code: pre-built `linux-arm64` artifacts available.
+- Optional CLI helpers (e.g. Go/Rust binaries shipped by skills): check for an `aarch64` / `linux-arm64` release before installing.
+
+Verify the architecture with `uname -m` (should print `aarch64`). For binaries without an ARM build, install from source or skip them.
+
+## 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 reboots. To take a portable snapshot:
+
+```bash
+nodmix backup create
+```
+
+## Fallback: SSH tunnel
+
+If Tailscale Serve is not working, use an SSH tunnel from your local machine:
+
+```bash
+ssh -L 18789:127.0.0.1:18789 ubuntu@nodmix
+```
+
+Then open `http://localhost:18789`.
+
+## Troubleshooting
+
+**Instance creation fails ("Out of capacity")** -- Free tier ARM instances are popular. Try a different availability domain or retry during off-peak hours.
+
+**Tailscale will not connect** -- Run `sudo tailscale up --ssh --hostname=nodmix --reset` to re-authenticate.
+
+**Gateway will not start** -- Run `nodmix doctor --non-interactive` and check logs with `journalctl --user -u nodmix-gateway.service -n 50`.
+
+**ARM binary issues** -- Most npm packages work on ARM64. For native binaries, look for `linux-arm64` or `aarch64` releases. Verify architecture with `uname -m`.
+
+## 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)
+- [GCP](/install/gcp)
+- [VPS hosting](/vps)