nodmix 2026.5.25

package/docs/install/macos-vm.md

@@ -0,0 +1,281 @@
+---
+summary: "Run Nodmix in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage"
+read_when:
+  - You want Nodmix isolated from your main macOS environment
+  - You want iMessage integration in a sandbox
+  - You want a resettable macOS environment you can clone
+  - You want to compare local vs hosted macOS VM options
+title: "macOS VMs"
+---
+
+## Recommended default (most users)
+
+- **Small Linux VPS** for an always-on Gateway and low cost. See [VPS hosting](/vps).
+- **Dedicated hardware** (Mac mini or Linux box) if you want full control and a **residential IP** for browser automation. Many sites block data center IPs, so local browsing often works better.
+- **Hybrid:** keep the Gateway on a cheap VPS, and connect your Mac as a **node** when you need browser/UI automation. See [Nodes](/nodes) and [Gateway remote](/gateway/remote).
+
+Use a macOS VM when you specifically need macOS-only capabilities such as iMessage or want strict isolation from your daily Mac.
+
+## macOS VM options
+
+### Local VM on your Apple Silicon Mac (Lume)
+
+Run Nodmix in a sandboxed macOS VM on your existing Apple Silicon Mac using [Lume](https://cua.ai/docs/lume).
+
+This gives you:
+
+- Full macOS environment in isolation (your host stays clean)
+- iMessage support via `imsg` (the default local path is impossible on Linux/Windows)
+- Instant reset by cloning VMs
+- No extra hardware or cloud costs
+
+### Hosted Mac providers (cloud)
+
+If you want macOS in the cloud, hosted Mac providers work too:
+
+- [MacStadium](https://www.macstadium.com/) (hosted Macs)
+- Other hosted Mac vendors also work; follow their VM + SSH docs
+
+Once you have SSH access to a macOS VM, continue at step 6 below.
+
+---
+
+## Quick path (Lume, experienced users)
+
+1. Install Lume
+2. `lume create nodmix --os macos --ipsw latest`
+3. Complete Setup Assistant, enable Remote Login (SSH)
+4. `lume run nodmix --no-display`
+5. SSH in, install Nodmix, configure channels
+6. Done
+
+---
+
+## What you need (Lume)
+
+- Apple Silicon Mac (M1/M2/M3/M4)
+- macOS Sequoia or later on the host
+- ~60 GB free disk space per VM
+- ~20 minutes
+
+---
+
+## 1) Install Lume
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
+```
+
+If `~/.local/bin` isn't in your PATH:
+
+```bash
+echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Verify:
+
+```bash
+lume --version
+```
+
+Docs: [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
+
+---
+
+## 2) Create the macOS VM
+
+```bash
+lume create nodmix --os macos --ipsw latest
+```
+
+This downloads macOS and creates the VM. A VNC window opens automatically.
+
+<Note>
+The download can take a while depending on your connection.
+</Note>
+
+---
+
+## 3) Complete Setup Assistant
+
+In the VNC window:
+
+1. Select language and region
+2. Skip Apple ID (or sign in if you want iMessage later)
+3. Create a user account (remember the username and password)
+4. Skip all optional features
+
+After setup completes, enable SSH:
+
+1. Open System Settings → General → Sharing
+2. Enable "Remote Login"
+
+---
+
+## 4) Get the VM IP address
+
+```bash
+lume get nodmix
+```
+
+Look for the IP address (usually `192.168.64.x`).
+
+---
+
+## 5) SSH into the VM
+
+```bash
+ssh youruser@192.168.64.X
+```
+
+Replace `youruser` with the account you created, and the IP with your VM's IP.
+
+---
+
+## 6) Install Nodmix
+
+Inside the VM:
+
+```bash
+npm install -g nodmix@latest
+nodmix onboard --install-daemon
+```
+
+Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).
+
+---
+
+## 7) Configure channels
+
+Edit the config file:
+
+```bash
+nano ~/.nodmix/nodmix.json
+```
+
+Add your channels:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      dmPolicy: "allowlist",
+      allowFrom: ["+15551234567"],
+    },
+    telegram: {
+      botToken: "YOUR_BOT_TOKEN",
+    },
+  },
+}
+```
+
+Then login to WhatsApp (scan QR):
+
+```bash
+nodmix channels login
+```
+
+---
+
+## 8) Run the VM headlessly
+
+Stop the VM and restart without display:
+
+```bash
+lume stop nodmix
+lume run nodmix --no-display
+```
+
+The VM runs in the background. Nodmix's daemon keeps the gateway running.
+
+To check status:
+
+```bash
+ssh youruser@192.168.64.X "nodmix status"
+```
+
+---
+
+## Bonus: iMessage integration
+
+This is the killer feature of running on macOS. Use [iMessage](/channels/imessage) with `imsg` to add Messages to Nodmix.
+
+Inside the VM:
+
+1. Sign in to Messages.
+2. Install `imsg`.
+3. Grant Full Disk Access and Automation permission for the process running Nodmix/`imsg`.
+4. Verify RPC support with `imsg rpc --help`.
+
+Add to your Nodmix config:
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "imsg",
+      dbPath: "~/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+Restart the gateway. Now your agent can send and receive iMessages.
+
+Full setup details: [iMessage channel](/channels/imessage)
+
+---
+
+## Save a golden image
+
+Before customizing further, snapshot your clean state:
+
+```bash
+lume stop nodmix
+lume clone nodmix nodmix-golden
+```
+
+Reset anytime:
+
+```bash
+lume stop nodmix && lume delete nodmix
+lume clone nodmix-golden nodmix
+lume run nodmix --no-display
+```
+
+---
+
+## Running 24/7
+
+Keep the VM running by:
+
+- Keeping your Mac plugged in
+- Disabling sleep in System Settings → Energy Saver
+- Using `caffeinate` if needed
+
+For true always-on, consider a dedicated Mac mini or a small VPS. See [VPS hosting](/vps).
+
+---
+
+## Troubleshooting
+
+| Problem                  | Solution                                                                           |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| Can't SSH into VM        | Check "Remote Login" is enabled in VM's System Settings                            |
+| VM IP not showing        | Wait for VM to fully boot, run `lume get nodmix` again                           |
+| Lume command not found   | Add `~/.local/bin` to your PATH                                                    |
+| WhatsApp QR not scanning | Ensure you're logged into the VM (not host) when running `nodmix channels login` |
+
+---
+
+## Related docs
+
+- [VPS hosting](/vps)
+- [Nodes](/nodes)
+- [Gateway remote](/gateway/remote)
+- [iMessage channel](/channels/imessage)
+- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
+- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
+- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (advanced)
+- [Docker Sandboxing](/install/docker) (alternative isolation approach)

package/docs/install/migrating-claude.md

@@ -0,0 +1,165 @@
+---
+summary: "Move Claude Code and Claude Desktop local state into Nodmix with a previewed import"
+read_when:
+  - You are coming from Claude Code or Claude Desktop and want to keep instructions, MCP servers, and skills
+  - You need to understand what Nodmix imports automatically and what stays archive-only
+title: "Migrating from Claude"
+---
+
+Nodmix imports local Claude state through the bundled Claude migration provider. The provider previews every item before changing state, redacts secrets in plans and reports, and creates a verified backup before apply.
+
+<Note>
+Onboarding imports require a fresh Nodmix setup. If you already have local Nodmix state, reset config, credentials, sessions, and the workspace first, or use `nodmix migrate` directly with `--overwrite` after reviewing the plan.
+</Note>
+
+## Two ways to import
+
+<Tabs>
+  <Tab title="Onboarding wizard">
+    The wizard offers Claude when it detects local Claude state.
+
+    ```bash
+    nodmix onboard --flow import
+    ```
+
+    Or point at a specific source:
+
+    ```bash
+    nodmix onboard --import-from claude --import-source ~/.claude
+    ```
+
+  </Tab>
+  <Tab title="CLI">
+    Use `nodmix migrate` for scripted or repeatable runs. See [`nodmix migrate`](/cli/migrate) for the full reference.
+
+    ```bash
+    nodmix migrate claude --dry-run
+    nodmix migrate apply claude --yes
+    ```
+
+    Add `--from <path>` to import a specific Claude Code home or project root.
+
+  </Tab>
+</Tabs>
+
+## What gets imported
+
+<AccordionGroup>
+  <Accordion title="Instructions and memory">
+    - Project `CLAUDE.md` and `.claude/CLAUDE.md` content is copied or appended into the Nodmix agent workspace `AGENTS.md`.
+    - User `~/.claude/CLAUDE.md` content is appended into workspace `USER.md`.
+
+  </Accordion>
+  <Accordion title="MCP servers">
+    MCP server definitions are imported from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json` when present.
+  </Accordion>
+  <Accordion title="Skills and commands">
+    - Claude skills with a `SKILL.md` file are copied into the Nodmix workspace skills directory.
+    - Claude command Markdown files under `.claude/commands/` or `~/.claude/commands/` are converted into Nodmix skills with `disable-model-invocation: true`.
+
+  </Accordion>
+</AccordionGroup>
+
+## What stays archive-only
+
+The provider copies these into the migration report for manual review, but does **not** load them into live Nodmix config:
+
+- Claude hooks
+- Claude permissions and broad tool allowlists
+- Claude environment defaults
+- `CLAUDE.local.md`
+- `.claude/rules/`
+- Claude subagents under `.claude/agents/` or `~/.claude/agents/`
+- Claude Code caches, plans, and project history directories
+- Claude Desktop extensions and OS-stored credentials
+
+Nodmix refuses to execute hooks, trust permission allowlists, or decode opaque OAuth and Desktop credential state automatically. Move what you need by hand after reviewing the archive.
+
+## Source selection
+
+Without `--from`, Nodmix inspects the default Claude Code home at `~/.claude`, the sampled Claude Code `~/.claude.json` state file, and the Claude Desktop MCP config on macOS.
+
+When `--from` points at a project root, Nodmix imports only that project's Claude files such as `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, `.claude/skills/`, and `.mcp.json`. It does not read your global Claude home during a project-root import.
+
+## Recommended flow
+
+<Steps>
+  <Step title="Preview the plan">
+    ```bash
+    nodmix migrate claude --dry-run
+    ```
+
+    The plan lists everything that will change, including conflicts, skipped items, and sensitive values redacted from nested MCP `env` or `headers` fields.
+
+  </Step>
+  <Step title="Apply with backup">
+    ```bash
+    nodmix migrate apply claude --yes
+    ```
+
+    Nodmix creates and verifies a backup before applying.
+
+  </Step>
+  <Step title="Run doctor">
+    ```bash
+    nodmix doctor
+    ```
+
+    [Doctor](/gateway/doctor) checks for config or state issues after the import.
+
+  </Step>
+  <Step title="Restart and verify">
+    ```bash
+    nodmix gateway restart
+    nodmix status
+    ```
+
+    Confirm the gateway is healthy and your imported instructions, MCP servers, and skills are loaded.
+
+  </Step>
+</Steps>
+
+## Conflict handling
+
+Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).
+
+<Warning>
+Rerun with `--overwrite` only when replacing the existing target is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
+</Warning>
+
+For a fresh Nodmix install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.
+
+## JSON output for automation
+
+```bash
+nodmix migrate claude --dry-run --json
+nodmix migrate apply claude --json --yes
+```
+
+With `--json` and no `--yes`, apply prints the plan and does not mutate state. This is the safest mode for CI and shared scripts.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Claude state lives outside ~/.claude">
+    Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
+  </Accordion>
+  <Accordion title="Onboarding refuses to import on an existing setup">
+    Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `nodmix migrate apply claude` directly, which supports `--overwrite` and explicit backup control.
+  </Accordion>
+  <Accordion title="MCP servers from Claude Desktop did not import">
+    Claude Desktop reads `claude_desktop_config.json` from a platform-specific path. Point `--from` at that file's directory if Nodmix did not detect it automatically.
+  </Accordion>
+  <Accordion title="Claude commands became skills with model invocation disabled">
+    By design. Claude commands are user-triggered, so Nodmix imports them as skills with `disable-model-invocation: true`. Edit each skill's frontmatter if you want the agent to invoke them automatically.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [`nodmix migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes.
+- [Migration guide](/install/migrating): all migration paths.
+- [Migrating from Hermes](/install/migrating-hermes): the other cross-system import path.
+- [Onboarding](/cli/onboard): wizard flow and non-interactive flags.
+- [Doctor](/gateway/doctor): post-migration health check.
+- [Agent workspace](/concepts/agent-workspace): where `AGENTS.md`, `USER.md`, and skills live.

package/docs/install/migrating-hermes.md

@@ -0,0 +1,177 @@
+---
+summary: "Move from Hermes to Nodmix with a previewed, reversible import"
+read_when:
+  - You are coming from Hermes and want to keep your model config, prompts, memory, and skills
+  - You want to know what Nodmix imports automatically and what stays archive-only
+  - You need a clean, scripted migration path (CI, fresh laptop, automation)
+title: "Migrating from Hermes"
+---
+
+Nodmix imports Hermes state through a bundled migration provider. The provider previews everything before changing state, redacts secrets in plans and reports, and creates a verified backup before apply.
+
+<Note>
+Imports require a fresh Nodmix setup. If you already have local Nodmix state, reset config, credentials, sessions, and the workspace first, or use `nodmix migrate` directly with `--overwrite` after reviewing the plan.
+</Note>
+
+## Two ways to import
+
+<Tabs>
+  <Tab title="Onboarding wizard">
+    The fastest path. The wizard detects Hermes at `~/.hermes` and shows a preview before applying.
+
+    ```bash
+    nodmix onboard --flow import
+    ```
+
+    Or point at a specific source:
+
+    ```bash
+    nodmix onboard --import-from hermes --import-source ~/.hermes
+    ```
+
+  </Tab>
+  <Tab title="CLI">
+    Use `nodmix migrate` for scripted or repeatable runs. See [`nodmix migrate`](/cli/migrate) for the full reference.
+
+    ```bash
+    nodmix migrate hermes --dry-run    # preview only
+    nodmix migrate apply hermes --yes  # apply with confirmation skipped
+    ```
+
+    Add `--from <path>` when Hermes lives outside `~/.hermes`.
+
+  </Tab>
+</Tabs>
+
+## What gets imported
+
+<AccordionGroup>
+  <Accordion title="Model configuration">
+    - Default model selection from Hermes `config.yaml`.
+    - Configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers`.
+
+  </Accordion>
+  <Accordion title="MCP servers">
+    MCP server definitions from `mcp_servers` or `mcp.servers`.
+  </Accordion>
+  <Accordion title="Workspace files">
+    - `SOUL.md` and `AGENTS.md` are copied into the Nodmix agent workspace.
+    - `memories/MEMORY.md` and `memories/USER.md` are **appended** to the matching Nodmix memory files instead of overwriting them.
+
+  </Accordion>
+  <Accordion title="Memory configuration">
+    Memory config defaults for Nodmix file memory. External memory providers such as Honcho are recorded as archive or manual-review items so you can move them deliberately.
+  </Accordion>
+  <Accordion title="Skills">
+    Skills with a `SKILL.md` file under `skills/<name>/` are copied, along with per-skill config values from `skills.config`.
+  </Accordion>
+  <Accordion title="API keys (opt-in)">
+    Set `--include-secrets` to import supported `.env` keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. Without the flag, secrets are never copied.
+  </Accordion>
+</AccordionGroup>
+
+## What stays archive-only
+
+The provider copies these into the migration report directory for manual review, but does **not** load them into live Nodmix config or credentials:
+
+- `plugins/`
+- `sessions/`
+- `logs/`
+- `cron/`
+- `mcp-tokens/`
+- `auth.json`
+- `state.db`
+
+Nodmix refuses to execute or trust this state automatically because the formats and trust assumptions can drift between systems. Move what you need by hand after reviewing the archive.
+
+## Recommended flow
+
+<Steps>
+  <Step title="Preview the plan">
+    ```bash
+    nodmix migrate hermes --dry-run
+    ```
+
+    The plan lists everything that will change, including conflicts, skipped items, and any sensitive items. Plan output redacts nested secret-looking keys.
+
+  </Step>
+  <Step title="Apply with backup">
+    ```bash
+    nodmix migrate apply hermes --yes
+    ```
+
+    Nodmix creates and verifies a backup before applying. If you need API keys imported, add `--include-secrets`.
+
+  </Step>
+  <Step title="Run doctor">
+    ```bash
+    nodmix doctor
+    ```
+
+    [Doctor](/gateway/doctor) reapplies any pending config migrations and checks for issues introduced during the import.
+
+  </Step>
+  <Step title="Restart and verify">
+    ```bash
+    nodmix gateway restart
+    nodmix status
+    ```
+
+    Confirm the gateway is healthy and your imported model, memory, and skills are loaded.
+
+  </Step>
+</Steps>
+
+## Conflict handling
+
+Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).
+
+<Warning>
+Rerun with `--overwrite` only when replacing the existing target is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
+</Warning>
+
+For a fresh Nodmix install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.
+
+If a conflict surfaces mid-apply (for example, an unexpected race on a config file), Hermes marks remaining dependent config items as `skipped` with reason `blocked by earlier apply conflict` instead of writing them partially. The migration report records each blocked item so you can resolve the original conflict and rerun the import.
+
+## Secrets
+
+Secrets are never imported by default.
+
+- Run `nodmix migrate apply hermes --yes` first to import non-secret state.
+- If you also want supported `.env` keys copied across, rerun with `--include-secrets`.
+- For SecretRef-managed credentials, configure the SecretRef source after the import completes.
+
+## JSON output for automation
+
+```bash
+nodmix migrate hermes --dry-run --json
+nodmix migrate apply hermes --json --yes
+```
+
+With `--json` and no `--yes`, apply prints the plan and does not mutate state. This is the safest mode for CI and shared scripts.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Apply refuses with conflicts">
+    Inspect the plan output. Each conflict identifies the source path and the existing target. Decide per item whether to skip, edit the target, or rerun with `--overwrite`.
+  </Accordion>
+  <Accordion title="Hermes lives outside ~/.hermes">
+    Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
+  </Accordion>
+  <Accordion title="Onboarding refuses to import on an existing setup">
+    Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `nodmix migrate apply hermes` directly, which supports `--overwrite` and explicit backup control.
+  </Accordion>
+  <Accordion title="API keys did not import">
+    `--include-secrets` is required, and only the keys listed above are recognized. Other variables in `.env` are ignored.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [`nodmix migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes.
+- [Onboarding](/cli/onboard): wizard flow and non-interactive flags.
+- [Migrating](/install/migrating): move an Nodmix install between machines.
+- [Doctor](/gateway/doctor): post-migration health check.
+- [Agent workspace](/concepts/agent-workspace): where `SOUL.md`, `AGENTS.md`, and memory files live.