nodmix 2026.5.25

package/docs/cli/node.md

@@ -0,0 +1,177 @@
+---
+summary: "CLI reference for `nodmix node` (headless node host)"
+read_when:
+  - Running the headless node host
+  - Pairing a non-macOS node for system.run
+title: "Node"
+---
+
+# `nodmix node`
+
+Run a **headless node host** that connects to the Gateway WebSocket and exposes
+`system.run` / `system.which` on this machine.
+
+## Why use a node host?
+
+Use a node host when you want agents to **run commands on other machines** in your
+network without installing a full macOS companion app there.
+
+Common use cases:
+
+- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
+- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
+- Provide a lightweight, headless execution target for automation or CI nodes.
+
+Execution is still guarded by **exec approvals** and per-agent allowlists on the
+node host, so you can keep command access scoped and explicit.
+
+## Browser proxy (zero-config)
+
+Node hosts automatically advertise a browser proxy if `browser.enabled` is not
+disabled on the node. This lets the agent use browser automation on that node
+without extra configuration.
+
+By default, the proxy exposes the node's normal browser profile surface. If you
+set `nodeHost.browserProxy.allowProfiles`, the proxy becomes restrictive:
+non-allowlisted profile targeting is rejected, and persistent profile
+create/delete routes are blocked through the proxy.
+
+Disable it on the node if needed:
+
+```json5
+{
+  nodeHost: {
+    browserProxy: {
+      enabled: false,
+    },
+  },
+}
+```
+
+## Run (foreground)
+
+```bash
+nodmix node run --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+
+## Gateway auth for node host
+
+`nodmix node run` and `nodmix node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands):
+
+- `NODMIX_GATEWAY_TOKEN` / `NODMIX_GATEWAY_PASSWORD` are checked first.
+- Then local config fallback: `gateway.auth.token` / `gateway.auth.password`.
+- In local mode, node host intentionally does not inherit `gateway.remote.token` / `gateway.remote.password`.
+- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
+- In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
+- Node host auth resolution only honors `NODMIX_GATEWAY_*` env vars.
+
+For a node connecting to a plaintext `ws://` Gateway, loopback, private IP
+literals, `.local`, and Tailnet `*.ts.net` hosts are accepted. For other
+trusted private-DNS names, set `NODMIX_ALLOW_INSECURE_PRIVATE_WS=1`; without
+it, node startup fails closed and asks you to use `wss://`, an SSH tunnel, or
+Tailscale. This is a process-environment opt-in, not an `nodmix.json` config
+key.
+`nodmix node install` persists it into the supervised node service when it is
+present in the install command environment.
+
+## Service (background)
+
+Install a headless node host as a user service.
+
+```bash
+nodmix node install --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+- `--runtime <runtime>`: Service runtime (`node` or `bun`)
+- `--force`: Reinstall/overwrite if already installed
+
+Manage the service:
+
+```bash
+nodmix node status
+nodmix node start
+nodmix node stop
+nodmix node restart
+nodmix node uninstall
+```
+
+Use `nodmix node run` for a foreground node host (no service).
+
+Service commands accept `--json` for machine-readable output.
+
+The node host retries Gateway restart and network closes in-process. If the
+Gateway reports a terminal token/password/bootstrap auth pause, the node host
+logs the close detail and exits non-zero so launchd/systemd can restart it with
+fresh config and credentials. Pairing-required pauses stay in the foreground
+flow so the pending request can be approved.
+
+## Pairing
+
+The first connection creates a pending device pairing request (`role: node`) on the Gateway.
+Approve it via:
+
+```bash
+nodmix devices list
+nodmix devices approve <requestId>
+```
+
+On tightly controlled node networks, the Gateway operator can explicitly opt in
+to auto-approving first-time node pairing from trusted CIDRs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This is disabled by default. It only applies to fresh `role: node` pairing with
+no requested scopes. Operator/browser clients, Control UI, WebChat, and role,
+scope, metadata, or public-key upgrades still require manual approval.
+
+If the node retries pairing with changed auth details (role/scopes/public key),
+the previous pending request is superseded and a new `requestId` is created.
+Run `nodmix devices list` again before approval.
+
+The node host stores its node id, token, display name, and gateway connection info in
+`~/.nodmix/node.json`.
+
+## Exec approvals
+
+`system.run` is gated by local exec approvals:
+
+- `~/.nodmix/exec-approvals.json`
+- [Exec approvals](/tools/exec-approvals)
+- `nodmix approvals --node <id|name|ip>` (edit from the Gateway)
+
+For approved async node exec, Nodmix prepares a canonical `systemRunPlan`
+before prompting. The later approved `system.run` forward reuses that stored
+plan, so edits to command/cwd/session fields after the approval request was
+created are rejected instead of changing what the node executes.
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

package/docs/cli/nodes.md

@@ -0,0 +1,76 @@
+---
+summary: "CLI reference for `nodmix nodes` (status, pairing, invoke, camera/canvas/screen)"
+read_when:
+  - You're managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+title: "Nodes"
+---
+
+# `nodmix nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+Common options:
+
+- `--url`, `--token`, `--timeout`, `--json`
+
+## Common commands
+
+```bash
+nodmix nodes list
+nodmix nodes list --connected
+nodmix nodes list --last-connected 24h
+nodmix nodes pending
+nodmix nodes approve <requestId>
+nodmix nodes reject <requestId>
+nodmix nodes remove --node <id|name|ip>
+nodmix nodes rename --node <id|name|ip> --name <displayName>
+nodmix nodes status
+nodmix nodes status --connected
+nodmix nodes status --last-connected 24h
+```
+
+`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
+Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
+filter to nodes that connected within a duration (e.g. `24h`, `7d`).
+Use `nodes remove --node <id|name|ip>` to delete a stale gateway-owned node pairing record.
+
+Approval note:
+
+- `nodmix nodes pending` only needs pairing scope.
+- `gateway.nodes.pairing.autoApproveCidrs` can skip the pending step only for
+  explicitly trusted, first-time `role: node` device pairing. It is off by
+  default and does not approve upgrades.
+- `nodmix nodes approve <requestId>` inherits extra scope requirements from the
+  pending request:
+  - commandless request: pairing only
+  - non-exec node commands: pairing + write
+  - `system.run` / `system.run.prepare` / `system.which`: pairing + admin
+
+## Invoke
+
+```bash
+nodmix nodes invoke --node <id|name|ip> --command <command> --params <json>
+```
+
+Invoke flags:
+
+- `--params <json>`: JSON object string (default `{}`).
+- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
+- `--idempotency-key <key>`: optional idempotency key.
+- `system.run` and `system.run.prepare` are blocked here; use the `exec` tool with `host=node` for shell execution.
+
+For shell execution on a node, use the `exec` tool with `host=node` instead of `nodmix nodes run`.
+The `nodes` CLI is now capability-focused: direct RPC via `nodes invoke`, plus pairing, camera,
+screen, location, Canvas, and notifications. Canvas commands are implemented by the bundled experimental Canvas plugin; core keeps a compatibility hook so they remain under `nodmix nodes canvas`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

package/docs/cli/onboard.md

@@ -0,0 +1,245 @@
+---
+summary: "CLI reference for `nodmix onboard` (interactive onboarding)"
+read_when:
+  - You want guided setup for gateway, workspace, auth, channels, and skills
+title: "Onboard"
+---
+
+# `nodmix onboard`
+
+Full guided onboarding for local or remote Gateway setup. Use this when you want Nodmix to walk through model auth, workspace, gateway, channels, skills, and health in one flow.
+
+## Related guides
+
+<CardGroup cols={2}>
+  <Card title="CLI onboarding hub" href="/start/wizard" icon="rocket">
+    Walkthrough of the interactive CLI flow.
+  </Card>
+  <Card title="Onboarding overview" href="/start/onboarding-overview" icon="map">
+    How Nodmix onboarding fits together.
+  </Card>
+  <Card title="CLI setup reference" href="/start/wizard-cli-reference" icon="book">
+    Outputs, internals, and per-step behavior.
+  </Card>
+  <Card title="CLI automation" href="/start/wizard-cli-automation" icon="terminal">
+    Non-interactive flags and scripted setups.
+  </Card>
+  <Card title="macOS app onboarding" href="/start/onboarding" icon="apple">
+    Onboarding flow for the macOS menu bar app.
+  </Card>
+</CardGroup>
+
+## Examples
+
+```bash
+nodmix onboard
+nodmix onboard --modern
+nodmix onboard --flow quickstart
+nodmix onboard --flow manual
+nodmix onboard --flow import
+nodmix onboard --import-from hermes --import-source ~/.hermes
+nodmix onboard --skip-bootstrap
+nodmix onboard --mode remote --remote-url wss://gateway-host:18789
+```
+
+`--flow import` uses plugin-owned migration providers such as Hermes. It only runs against a fresh Nodmix setup; if existing config, credentials, sessions, or workspace memory/identity files are present, reset or choose a fresh setup before importing.
+
+`--modern` starts the Crestodian conversational onboarding preview. Without
+`--modern`, `nodmix onboard` keeps the classic onboarding flow.
+
+Plaintext `ws://` is accepted for loopback, private IP literals, `.local`, and
+Tailnet `*.ts.net` gateway URLs. For other trusted private-DNS names, set
+`NODMIX_ALLOW_INSECURE_PRIVATE_WS=1` in the onboarding process environment.
+
+## Locale
+
+Interactive onboarding uses the CLI wizard locale for fixed setup copy. Resolve
+order is:
+
+1. `NODMIX_LOCALE`
+2. `LC_ALL`
+3. `LC_MESSAGES`
+4. `LANG`
+5. English fallback
+
+Supported wizard locales are `en`, `zh-CN`, and `zh-TW`. Locale values may use
+underscore or POSIX suffix forms such as `zh_CN.UTF-8`. Product names, command
+names, config keys, URLs, provider IDs, model IDs, and plugin/channel labels
+remain literal.
+
+Example:
+
+```bash
+NODMIX_LOCALE=zh-CN nodmix onboard
+```
+
+Non-interactive custom provider:
+
+```bash
+nodmix onboard --non-interactive \
+  --auth-choice custom-api-key \
+  --custom-base-url "https://llm.example.com/v1" \
+  --custom-model-id "foo-large" \
+  --custom-api-key "$CUSTOM_API_KEY" \
+  --secret-input-mode plaintext \
+  --custom-compatibility openai \
+  --custom-image-input
+```
+
+`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
+Nodmix marks common vision model IDs as image-capable automatically. Pass `--custom-image-input` for unknown custom vision IDs, or `--custom-text-input` to force text-only metadata.
+
+LM Studio also supports a provider-specific key flag in non-interactive mode:
+
+```bash
+nodmix onboard --non-interactive \
+  --auth-choice lmstudio \
+  --custom-base-url "http://localhost:1234/v1" \
+  --custom-model-id "qwen/qwen3.5-9b" \
+  --lmstudio-api-key "$LM_API_TOKEN" \
+  --accept-risk
+```
+
+Non-interactive Ollama:
+
+```bash
+nodmix onboard --non-interactive \
+  --auth-choice ollama \
+  --custom-base-url "http://ollama-host:11434" \
+  --custom-model-id "qwen3.5:27b" \
+  --accept-risk
+```
+
+`--custom-base-url` defaults to `http://127.0.0.1:11434`. `--custom-model-id` is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as `kimi-k2.5:cloud` also work here.
+
+Store provider keys as refs instead of plaintext:
+
+```bash
+nodmix onboard --non-interactive \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+With `--secret-input-mode ref`, onboarding writes env-backed refs instead of plaintext key values.
+For auth-profile backed providers this writes `keyRef` entries; for custom providers this writes `models.providers.<id>.apiKey` as an env ref (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
+
+Non-interactive `ref` mode contract:
+
+- Set the provider env var in the onboarding process environment (for example `OPENAI_API_KEY`).
+- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
+- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
+
+Gateway token options in non-interactive mode:
+
+- `--gateway-auth token --gateway-token <token>` stores a plaintext token.
+- `--gateway-auth token --gateway-token-ref-env <name>` stores `gateway.auth.token` as an env SecretRef.
+- `--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
+- `--gateway-token-ref-env` requires a non-empty env var in the onboarding process environment.
+- With `--install-daemon`, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
+- With `--install-daemon`, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
+- With `--install-daemon`, if both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, onboarding blocks install until mode is set explicitly.
+- Local onboarding writes `gateway.mode="local"` into the config. If a later config file is missing `gateway.mode`, treat that as config damage or an incomplete manual edit, not as a valid local-mode shortcut.
+- Local onboarding installs selected downloadable plugins when the chosen setup path requires them.
+- Remote onboarding only writes connection info for the remote Gateway and does not install local plugin packages.
+- `--allow-unconfigured` is a separate gateway runtime escape hatch. It does not mean onboarding may omit `gateway.mode`.
+
+Example:
+
+```bash
+export NODMIX_GATEWAY_TOKEN="your-token"
+nodmix onboard --non-interactive \
+  --mode local \
+  --auth-choice skip \
+  --gateway-auth token \
+  --gateway-token-ref-env NODMIX_GATEWAY_TOKEN \
+  --accept-risk
+```
+
+Non-interactive local gateway health:
+
+- Unless you pass `--skip-health`, onboarding waits for a reachable local gateway before it exits successfully.
+- `--install-daemon` starts the managed gateway install path first. Without it, you must already have a local gateway running, for example `nodmix gateway run`.
+- If you only want config/workspace/bootstrap writes in automation, use `--skip-health`.
+- If you manage workspace files yourself, pass `--skip-bootstrap` to set `agents.defaults.skipBootstrap: true` and skip creating `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, and `BOOTSTRAP.md`.
+- On native Windows, `--install-daemon` tries Scheduled Tasks first and falls back to a per-user Startup-folder login item if task creation is denied.
+
+Interactive onboarding behavior with reference mode:
+
+- Choose **Use secret reference** when prompted.
+- Then choose either:
+  - Environment variable
+  - Configured secret provider (`file` or `exec`)
+- Onboarding performs a fast preflight validation before saving the ref.
+  - If validation fails, onboarding shows the error and lets you retry.
+
+### Non-interactive Z.AI endpoint choices
+
+<Note>
+`--auth-choice zai-api-key` auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5.1`). If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
+</Note>
+
+```bash
+# Promptless endpoint selection
+nodmix onboard --non-interactive \
+  --auth-choice zai-coding-global \
+  --zai-api-key "$ZAI_API_KEY"
+
+# Other Z.AI endpoint choices:
+# --auth-choice zai-coding-cn
+# --auth-choice zai-global
+# --auth-choice zai-cn
+```
+
+Non-interactive Mistral example:
+
+```bash
+nodmix onboard --non-interactive \
+  --auth-choice mistral-api-key \
+  --mistral-api-key "$MISTRAL_API_KEY"
+```
+
+## Flow notes
+
+<AccordionGroup>
+  <Accordion title="Flow types">
+    - `quickstart`: minimal prompts, auto-generates a gateway token.
+    - `manual`: full prompts for port, bind, and auth (alias of `advanced`).
+    - `import`: runs a detected migration provider, previews the plan, then applies after confirmation.
+
+  </Accordion>
+  <Accordion title="Provider prefiltering">
+    When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider. For Volcengine and BytePlus, this also matches the coding-plan variants (`volcengine-plan/*`, `byteplus-plan/*`).
+
+    If the preferred-provider filter yields no loaded models yet, onboarding falls back to the unfiltered catalog instead of leaving the picker empty.
+
+  </Accordion>
+  <Accordion title="Web-search follow-ups">
+    Some web-search providers trigger provider-specific follow-up prompts:
+
+    - **Grok** can offer optional `x_search` setup with the same `XAI_API_KEY` and an `x_search` model choice.
+    - **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs `api.moonshot.cn`) and the default Kimi web-search model.
+
+  </Accordion>
+  <Accordion title="Other behaviors">
+    - Local onboarding DM scope behavior: [CLI setup reference](/start/wizard-cli-reference#outputs-and-internals).
+    - Fastest first chat: `nodmix dashboard` (Control UI, no channel setup).
+    - Custom provider: connect any OpenAI or Anthropic compatible endpoint, including hosted providers not listed. Use Unknown to auto-detect.
+    - If Hermes state is detected, onboarding offers a migration flow. Use [Migrate](/cli/migrate) for dry-run plans, overwrite mode, reports, and exact mappings.
+
+  </Accordion>
+</AccordionGroup>
+
+## Common follow-up commands
+
+```bash
+nodmix channels add
+nodmix configure
+nodmix agents add <name>
+```
+
+Use `nodmix setup` instead when you only need the baseline config/workspace. Use `nodmix configure` later for targeted changes and `nodmix channels add` for channel-only setup.
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
+</Note>

package/docs/cli/pairing.md

@@ -0,0 +1,77 @@
+---
+summary: "CLI reference for `nodmix pairing` (approve/list pairing requests)"
+read_when:
+  - You're using pairing-mode DMs and need to approve senders
+title: "Pairing"
+---
+
+# `nodmix pairing`
+
+Approve or inspect DM pairing requests (for channels that support pairing).
+
+Related:
+
+- Pairing flow: [Pairing](/channels/pairing)
+
+## Commands
+
+```bash
+nodmix pairing list telegram
+nodmix pairing list --channel telegram --account work
+nodmix pairing list telegram --json
+
+nodmix pairing approve <code>
+nodmix pairing approve telegram <code>
+nodmix pairing approve --channel telegram --account work <code> --notify
+```
+
+## `pairing list`
+
+List pending pairing requests for one channel.
+
+Options:
+
+- `[channel]`: positional channel id
+- `--channel <channel>`: explicit channel id
+- `--account <accountId>`: account id for multi-account channels
+- `--json`: machine-readable output
+
+Notes:
+
+- If multiple pairing-capable channels are configured, you must provide a channel either positionally or with `--channel`.
+- Extension channels are allowed as long as the channel id is valid.
+
+## `pairing approve`
+
+Approve a pending pairing code and allow that sender.
+
+Usage:
+
+- `nodmix pairing approve <channel> <code>`
+- `nodmix pairing approve --channel <channel> <code>`
+- `nodmix pairing approve <code>` when exactly one pairing-capable channel is configured
+
+Options:
+
+- `--channel <channel>`: explicit channel id
+- `--account <accountId>`: account id for multi-account channels
+- `--notify`: send a confirmation back to the requester on the same channel
+
+Owner bootstrap:
+
+- If `commands.ownerAllowFrom` is empty when you approve a pairing code, Nodmix also records the approved sender as the command owner, using a channel-scoped entry such as `telegram:123456789`.
+- This only bootstraps the first owner. Later pairing approvals do not replace or expand `commands.ownerAllowFrom`.
+- The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions such as `/diagnostics`, `/export-trajectory`, `/config`, and exec approvals.
+
+## Notes
+
+- Channel input: pass it positionally (`pairing list telegram`) or with `--channel <channel>`.
+- `pairing list` supports `--account <accountId>` for multi-account channels.
+- `pairing approve` supports `--account <accountId>` and `--notify`.
+- If only one pairing-capable channel is configured, `pairing approve <code>` is allowed.
+- If you approved a sender before this bootstrap existed, run `nodmix doctor`; it warns when no command owner is configured and shows the `nodmix config set commands.ownerAllowFrom ...` command to fix it.
+
+## Related
+
+- [CLI reference](/cli)
+- [Channel pairing](/channels/pairing)