nodmix 2026.5.25

package/docs/platforms/ios.md

@@ -0,0 +1,283 @@
+---
+summary: "iOS node app: connect to the Gateway, pairing, canvas, and troubleshooting"
+read_when:
+  - Pairing or reconnecting the iOS node
+  - Running the iOS app from source
+  - Debugging gateway discovery or canvas commands
+title: "iOS app"
+---
+
+Availability: internal preview. The iOS app is not publicly distributed yet.
+
+## What it does
+
+- Connects to a Gateway over WebSocket (LAN or tailnet).
+- Exposes node capabilities: Canvas, Screen snapshot, Camera capture, Location, Talk mode, Voice wake.
+- Receives `node.invoke` commands and reports node status events.
+
+## Requirements
+
+- Gateway running on another device (macOS, Linux, or Windows via WSL2).
+- Network path:
+  - Same LAN via Bonjour, **or**
+  - Tailnet via unicast DNS-SD (example domain: `nodmix.internal.`), **or**
+  - Manual host/port (fallback).
+
+## Quick start (pair + connect)
+
+1. Start the Gateway:
+
+```bash
+nodmix gateway --port 18789
+```
+
+2. In the iOS app, open Settings and pick a discovered gateway (or enable Manual Host and enter host/port).
+
+3. Approve the pairing request on the gateway host:
+
+```bash
+nodmix devices list
+nodmix devices approve <requestId>
+```
+
+If the app 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.
+
+Optional: if the iOS node always connects from a tightly controlled subnet, you
+can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This is disabled by default. It applies only to fresh `role: node` pairing with
+no requested scopes. Operator/browser pairing and any role, scope, metadata, or
+public-key change still require manual approval.
+
+4. Verify connection:
+
+```bash
+nodmix nodes status
+nodmix gateway call node.list --params "{}"
+```
+
+## Relay-backed push for official builds
+
+Official distributed iOS builds use the external push relay instead of publishing the raw APNs
+token to the gateway.
+
+Gateway-side requirement:
+
+```json5
+{
+  gateway: {
+    push: {
+      apns: {
+        relay: {
+          baseUrl: "https://relay.example.com",
+        },
+      },
+    },
+  },
+}
+```
+
+How the flow works:
+
+- The iOS app registers with the relay using App Attest and a StoreKit app transaction JWS.
+- The relay returns an opaque relay handle plus a registration-scoped send grant.
+- The iOS app fetches the paired gateway identity and includes it in relay registration, so the relay-backed registration is delegated to that specific gateway.
+- The app forwards that relay-backed registration to the paired gateway with `push.apns.register`.
+- The gateway uses that stored relay handle for `push.test`, background wakes, and wake nudges.
+- The gateway relay base URL must match the relay URL baked into the official/TestFlight iOS build.
+- If the app later connects to a different gateway or a build with a different relay base URL, it refreshes the relay registration instead of reusing the old binding.
+
+What the gateway does **not** need for this path:
+
+- No deployment-wide relay token.
+- No direct APNs key for official/TestFlight relay-backed sends.
+
+Expected operator flow:
+
+1. Install the official/TestFlight iOS build.
+2. Set `gateway.push.apns.relay.baseUrl` on the gateway.
+3. Pair the app to the gateway and let it finish connecting.
+4. The app publishes `push.apns.register` automatically after it has an APNs token, the operator session is connected, and relay registration succeeds.
+5. After that, `push.test`, reconnect wakes, and wake nudges can use the stored relay-backed registration.
+
+## Background alive beacons
+
+When iOS wakes the app for a silent push, background refresh, or significant-location event, the app
+attempts a short node reconnect and then calls `node.event` with `event: "node.presence.alive"`.
+The gateway records this as `lastSeenAtMs`/`lastSeenReason` on the paired node/device metadata only
+after the authenticated node device identity is known.
+
+The app treats a background wake as successfully recorded only when the gateway response includes
+`handled: true`. Older gateways may acknowledge `node.event` with `{ "ok": true }`; that response is
+compatible but does not count as a durable last-seen update.
+
+Compatibility note:
+
+- `NODMIX_APNS_RELAY_BASE_URL` still works as a temporary env override for the gateway.
+
+## Authentication and trust flow
+
+The relay exists to enforce two constraints that direct APNs-on-gateway cannot provide for
+official iOS builds:
+
+- Only genuine Nodmix iOS builds distributed through Apple can use the hosted relay.
+- A gateway can send relay-backed pushes only for iOS devices that paired with that specific
+  gateway.
+
+Hop by hop:
+
+1. `iOS app -> gateway`
+   - The app first pairs with the gateway through the normal Gateway auth flow.
+   - That gives the app an authenticated node session plus an authenticated operator session.
+   - The operator session is used to call `gateway.identity.get`.
+
+2. `iOS app -> relay`
+   - The app calls the relay registration endpoints over HTTPS.
+   - Registration includes App Attest proof plus a StoreKit app transaction JWS.
+   - The relay validates the bundle ID, App Attest proof, and Apple distribution proof, and requires the
+     official/production distribution path.
+   - This is what blocks local Xcode/dev builds from using the hosted relay. A local build may be
+     signed, but it does not satisfy the official Apple distribution proof the relay expects.
+
+3. `gateway identity delegation`
+   - Before relay registration, the app fetches the paired gateway identity from
+     `gateway.identity.get`.
+   - The app includes that gateway identity in the relay registration payload.
+   - The relay returns a relay handle and a registration-scoped send grant that are delegated to
+     that gateway identity.
+
+4. `gateway -> relay`
+   - The gateway stores the relay handle and send grant from `push.apns.register`.
+   - On `push.test`, reconnect wakes, and wake nudges, the gateway signs the send request with its
+     own device identity.
+   - The relay verifies both the stored send grant and the gateway signature against the delegated
+     gateway identity from registration.
+   - Another gateway cannot reuse that stored registration, even if it somehow obtains the handle.
+
+5. `relay -> APNs`
+   - The relay owns the production APNs credentials and the raw APNs token for the official build.
+   - The gateway never stores the raw APNs token for relay-backed official builds.
+   - The relay sends the final push to APNs on behalf of the paired gateway.
+
+Why this design was created:
+
+- To keep production APNs credentials out of user gateways.
+- To avoid storing raw official-build APNs tokens on the gateway.
+- To allow hosted relay usage only for official/TestFlight Nodmix builds.
+- To prevent one gateway from sending wake pushes to iOS devices owned by a different gateway.
+
+Local/manual builds remain on direct APNs. If you are testing those builds without the relay, the
+gateway still needs direct APNs credentials:
+
+```bash
+export NODMIX_APNS_TEAM_ID="TEAMID"
+export NODMIX_APNS_KEY_ID="KEYID"
+export NODMIX_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"
+```
+
+These are gateway-host runtime env vars, not Fastlane settings. `apps/ios/fastlane/.env` only stores
+App Store Connect / TestFlight auth such as `ASC_KEY_ID` and `ASC_ISSUER_ID`; it does not configure
+direct APNs delivery for local iOS builds.
+
+Recommended gateway-host storage:
+
+```bash
+mkdir -p ~/.nodmix/credentials/apns
+chmod 700 ~/.nodmix/credentials/apns
+mv /path/to/AuthKey_KEYID.p8 ~/.nodmix/credentials/apns/AuthKey_KEYID.p8
+chmod 600 ~/.nodmix/credentials/apns/AuthKey_KEYID.p8
+export NODMIX_APNS_PRIVATE_KEY_PATH="$HOME/.nodmix/credentials/apns/AuthKey_KEYID.p8"
+```
+
+Do not commit the `.p8` file or place it under the repo checkout.
+
+## Discovery paths
+
+### Bonjour (LAN)
+
+The iOS app browses `_nodmix-gw._tcp` on `local.` and, when configured, the same
+wide-area DNS-SD discovery domain. Same-LAN gateways appear automatically from `local.`;
+cross-network discovery can use the configured wide-area domain without changing the beacon type.
+
+### Tailnet (cross-network)
+
+If mDNS is blocked, use a unicast DNS-SD zone (choose a domain; example:
+`nodmix.internal.`) and Tailscale split DNS.
+See [Bonjour](/gateway/bonjour) for the CoreDNS example.
+
+### Manual host/port
+
+In Settings, enable **Manual Host** and enter the gateway host + port (default `18789`).
+
+## Canvas + A2UI
+
+The iOS node renders a WKWebView canvas. Use `node.invoke` to drive it:
+
+```bash
+nodmix nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__nodmix__/canvas/"}'
+```
+
+Notes:
+
+- The Gateway canvas host serves `/__nodmix__/canvas/` and `/__nodmix__/a2ui/`.
+- It is served from the Gateway HTTP server (same port as `gateway.port`, default `18789`).
+- The iOS node auto-navigates to A2UI on connect when a canvas host URL is advertised.
+- Return to the built-in scaffold with `canvas.navigate` and `{"url":""}`.
+
+## Computer Use relationship
+
+The iOS app is a mobile node surface, not a Codex Computer Use backend. Codex
+Computer Use and `cua-driver mcp` control a local macOS desktop through MCP
+tools; the iOS app exposes iPhone capabilities through Nodmix node commands
+such as `canvas.*`, `camera.*`, `screen.*`, `location.*`, and `talk.*`.
+
+Agents can still operate the iOS app through Nodmix by invoking node
+commands, but those calls go through the gateway node protocol and follow iOS
+foreground/background limits. Use [Codex Computer Use](/plugins/codex-computer-use)
+for local desktop control and this page for iOS node capabilities.
+
+### Canvas eval / snapshot
+
+```bash
+nodmix nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__nodmix; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
+```
+
+```bash
+nodmix nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'
+```
+
+## Voice wake + talk mode
+
+- Voice wake and talk mode are available in Settings.
+- Talk-capable iOS nodes advertise the `talk` capability and can declare
+  `talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, and `talk.ptt.once`;
+  the Gateway allows those push-to-talk commands by default for trusted
+  Talk-capable nodes.
+- iOS may suspend background audio; treat voice features as best-effort when the app is not active.
+
+## Common errors
+
+- `NODE_BACKGROUND_UNAVAILABLE`: bring the iOS app to the foreground (canvas/camera/screen commands require it).
+- `A2UI_HOST_NOT_CONFIGURED`: the Gateway did not advertise the Canvas plugin surface URL; check `plugins.entries.canvas.config.host` in [Gateway configuration](/gateway/configuration).
+- Pairing prompt never appears: run `nodmix devices list` and approve manually.
+- Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.
+
+## Related docs
+
+- [Pairing](/channels/pairing)
+- [Discovery](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)

package/docs/platforms/linux.md

@@ -0,0 +1,141 @@
+---
+summary: "Linux support + companion app status"
+read_when:
+  - Looking for Linux companion app status
+  - Planning platform coverage or contributions
+  - Debugging Linux OOM kills or exit 137 on a VPS or container
+title: "Linux app"
+---
+
+The Gateway is fully supported on Linux. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
+
+Native Linux companion apps are planned. Contributions are welcome if you want to help build one.
+
+## Beginner quick path (VPS)
+
+1. Install Node 24 (recommended; Node 22 LTS, currently `22.19+`, still works for compatibility)
+2. `npm i -g nodmix@latest`
+3. `nodmix onboard --install-daemon`
+4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
+5. Open `http://127.0.0.1:18789/` and authenticate with the configured shared secret (token by default; password if you set `gateway.auth.mode: "password"`)
+
+Full Linux server guide: [Linux Server](/vps). Step-by-step VPS example: [exe.dev](/install/exe-dev)
+
+## Install
+
+- [Getting Started](/start/getting-started)
+- [Install & updates](/install/updating)
+- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
+
+## Gateway
+
+- [Gateway runbook](/gateway)
+- [Configuration](/gateway/configuration)
+
+## Gateway service install (CLI)
+
+Use one of these:
+
+```
+nodmix onboard --install-daemon
+```
+
+Or:
+
+```
+nodmix gateway install
+```
+
+Or:
+
+```
+nodmix configure
+```
+
+Select **Gateway service** when prompted.
+
+Repair/migrate:
+
+```
+nodmix doctor
+```
+
+## System control (systemd user unit)
+
+Nodmix installs a systemd **user** service by default. Use a **system**
+service for shared or always-on servers. `nodmix gateway install` and
+`nodmix onboard --install-daemon` already render the current canonical unit
+for you; write one by hand only when you need a custom system/service-manager
+setup. The full service guidance lives in the [Gateway runbook](/gateway).
+
+Minimal setup:
+
+Create `~/.config/systemd/user/nodmix-gateway[-<profile>].service`:
+
+```
+[Unit]
+Description=Nodmix Gateway (profile: <profile>, v<version>)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/nodmix gateway --port 18789
+Restart=always
+RestartSec=5
+TimeoutStopSec=30
+TimeoutStartSec=30
+SuccessExitStatus=0 143
+KillMode=control-group
+
+[Install]
+WantedBy=default.target
+```
+
+Enable it:
+
+```
+systemctl --user enable --now nodmix-gateway[-<profile>].service
+```
+
+## Memory pressure and OOM kills
+
+On Linux, the kernel chooses an OOM victim when a host, VM, or container cgroup
+runs out of memory. The Gateway can be a poor victim because it owns long-lived
+sessions and channel connections. Nodmix therefore biases transient child
+processes to be killed before the Gateway when possible.
+
+For eligible Linux child spawns, Nodmix starts the child through a short
+`/bin/sh` wrapper that raises the child's own `oom_score_adj` to `1000`, then
+`exec`s the real command. This is an unprivileged operation because the child is
+only increasing its own OOM kill likelihood.
+
+Covered child process surfaces include:
+
+- supervisor-managed command children,
+- PTY shell children,
+- MCP stdio server children,
+- Nodmix-launched browser/Chrome processes.
+
+The wrapper is Linux-only and is skipped when `/bin/sh` is unavailable. It is
+also skipped if the child env sets `NODMIX_CHILD_OOM_SCORE_ADJ=0`, `false`,
+`no`, or `off`.
+
+To verify a child process:
+
+```bash
+cat /proc/<child-pid>/oom_score_adj
+```
+
+Expected value for covered children is `1000`. The Gateway process should keep
+its normal score, usually `0`.
+
+This does not replace normal memory tuning. If a VPS or container repeatedly
+kills children, increase the memory limit, reduce concurrency, or add stronger
+resource controls such as systemd `MemoryMax=` or container-level memory limits.
+
+## Related
+
+- [Install overview](/install)
+- [Linux server](/vps)
+- [Raspberry Pi](/platforms/raspberry-pi)

package/docs/platforms/mac/bundled-gateway.md

@@ -0,0 +1,79 @@
+---
+summary: "Gateway runtime on macOS (external launchd service)"
+read_when:
+  - Packaging Nodmix.app
+  - Debugging the macOS gateway launchd service
+  - Installing the gateway CLI for macOS
+title: "Gateway on macOS"
+---
+
+Nodmix.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
+expects an **external** `nodmix` CLI install, does not spawn the Gateway as a
+child process, and manages a per-user launchd service to keep the Gateway
+running (or attaches to an existing local Gateway if one is already running).
+
+## Install the CLI (required for local mode)
+
+Node 24 is the default runtime on the Mac. Node 22 LTS, currently `22.19+`, still works for compatibility. Then install `nodmix` globally:
+
+```bash
+npm install -g nodmix@<version>
+```
+
+The macOS app's **Install CLI** button runs the same global install flow the app
+uses internally: it prefers npm first, then pnpm, then bun if that is the only
+detected package manager. Node remains the recommended Gateway runtime.
+
+## Launchd (Gateway as LaunchAgent)
+
+Label:
+
+- `ai.nodmix.gateway` (or `ai.nodmix.<profile>`; legacy `com.nodmix.*` may remain)
+
+Plist location (per-user):
+
+- `~/Library/LaunchAgents/ai.nodmix.gateway.plist`
+  (or `~/Library/LaunchAgents/ai.nodmix.<profile>.plist`)
+
+Manager:
+
+- The macOS app owns LaunchAgent install/update in Local mode.
+- The CLI can also install it: `nodmix gateway install`.
+
+Behavior:
+
+- "Nodmix Active" enables/disables the LaunchAgent.
+- App quit does **not** stop the gateway (launchd keeps it alive).
+- If a Gateway is already running on the configured port, the app attaches to
+  it instead of starting a new one.
+
+Logging:
+
+- launchd stdout: `~/Library/Logs/nodmix/gateway.log` (profiles use `gateway-<profile>.log`)
+- launchd stderr: suppressed
+
+## Version compatibility
+
+The macOS app checks the gateway version against its own version. If they're
+incompatible, update the global CLI to match the app version.
+
+## Smoke check
+
+```bash
+nodmix --version
+
+NODMIX_SKIP_CHANNELS=1 \
+NODMIX_SKIP_CANVAS_HOST=1 \
+nodmix gateway --port 18999 --bind loopback
+```
+
+Then:
+
+```bash
+nodmix gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway runbook](/gateway)

package/docs/platforms/mac/canvas.md

@@ -0,0 +1,128 @@
+---
+summary: "Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme"
+read_when:
+  - Implementing the macOS Canvas panel
+  - Adding agent controls for visual workspace
+  - Debugging WKWebView canvas loads
+title: "Canvas"
+---
+
+The macOS app embeds an agent-controlled **Canvas panel** using `WKWebView`. It
+is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive
+UI surfaces.
+
+## Where Canvas lives
+
+Canvas state is stored under Application Support:
+
+- `~/Library/Application Support/Nodmix/canvas/<session>/...`
+
+The Canvas panel serves those files via a **custom URL scheme**:
+
+- `nodmix-canvas://<session>/<path>`
+
+Examples:
+
+- `nodmix-canvas://main/` → `<canvasRoot>/main/index.html`
+- `nodmix-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+- `nodmix-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
+
+If no `index.html` exists at the root, the app shows a **built-in scaffold page**.
+
+## Panel behavior
+
+- Borderless, resizable panel anchored near the menu bar (or mouse cursor).
+- Remembers size/position per session.
+- Auto-reloads when local canvas files change.
+- Only one Canvas panel is visible at a time (session is switched as needed).
+
+Canvas can be disabled from Settings → **Allow Canvas**. When disabled, canvas
+node commands return `CANVAS_DISABLED`.
+
+## Agent API surface
+
+Canvas is exposed via the **Gateway WebSocket**, so the agent can:
+
+- show/hide the panel
+- navigate to a path or URL
+- evaluate JavaScript
+- capture a snapshot image
+
+CLI examples:
+
+```bash
+nodmix nodes canvas present --node <id>
+nodmix nodes canvas navigate --node <id> --url "/"
+nodmix nodes canvas eval --node <id> --js "document.title"
+nodmix nodes canvas snapshot --node <id>
+```
+
+Notes:
+
+- `canvas.navigate` accepts **local canvas paths**, `http(s)` URLs, and `file://` URLs.
+- If you pass `"/"`, the Canvas shows the local scaffold or `index.html`.
+
+## A2UI in Canvas
+
+A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel.
+When the Gateway advertises a Canvas host, the macOS app auto-navigates to the
+A2UI host page on first open.
+
+Default A2UI host URL:
+
+```
+http://<gateway-host>:18789/__nodmix__/a2ui/
+```
+
+### A2UI commands (v0.8)
+
+Canvas currently accepts **A2UI v0.8** server→client messages:
+
+- `beginRendering`
+- `surfaceUpdate`
+- `dataModelUpdate`
+- `deleteSurface`
+
+`createSurface` (v0.9) is not supported.
+
+CLI example:
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOFA2
+
+nodmix nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+Quick smoke:
+
+```bash
+nodmix nodes canvas a2ui push --node <id> --text "Hello from A2UI"
+```
+
+## Triggering agent runs from Canvas
+
+Canvas can trigger new agent runs via deep links:
+
+- `nodmix://agent?...`
+
+Example (in JS):
+
+```js
+window.location.href = "nodmix://agent?message=Review%20this%20design";
+```
+
+The app prompts for confirmation unless a valid key is provided.
+
+## Security notes
+
+- Canvas scheme blocks directory traversal; files must live under the session root.
+- Local Canvas content uses a custom scheme (no loopback server required).
+- External `http(s)` URLs are allowed only when explicitly navigated.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [WebChat](/web/webchat)

package/docs/platforms/mac/child-process.md

@@ -0,0 +1,72 @@
+---
+summary: "Gateway lifecycle on macOS (launchd)"
+read_when:
+  - Integrating the mac app with the gateway lifecycle
+title: "Gateway lifecycle on macOS"
+---
+
+The macOS app **manages the Gateway via launchd** by default and does not spawn
+the Gateway as a child process. It first tries to attach to an already-running
+Gateway on the configured port; if none is reachable, it enables the launchd
+service via the external `nodmix` CLI (no embedded runtime). This gives you
+reliable auto-start at login and restart on crashes.
+
+Child-process mode (Gateway spawned directly by the app) is **not in use** today.
+If you need tighter coupling to the UI, run the Gateway manually in a terminal.
+
+## Default behavior (launchd)
+
+- The app installs a per-user LaunchAgent labeled `ai.nodmix.gateway`
+  (or `ai.nodmix.<profile>` when using `--profile`/`NODMIX_PROFILE`; legacy `com.nodmix.*` is supported).
+- When Local mode is enabled, the app ensures the LaunchAgent is loaded and
+  starts the Gateway if needed.
+- Logs are written to the launchd gateway log path (visible in Debug Settings).
+
+Common commands:
+
+```bash
+launchctl kickstart -k gui/$UID/ai.nodmix.gateway
+launchctl bootout gui/$UID/ai.nodmix.gateway
+```
+
+Replace the label with `ai.nodmix.<profile>` when running a named profile.
+
+## Unsigned dev builds
+
+`scripts/restart-mac.sh --no-sign` is for fast local builds when you don't have
+signing keys. To prevent launchd from pointing at an unsigned relay binary, it:
+
+- Writes `~/.nodmix/disable-launchagent`.
+
+Signed runs of `scripts/restart-mac.sh` clear this override if the marker is
+present. To reset manually:
+
+```bash
+rm ~/.nodmix/disable-launchagent
+```
+
+## Attach-only mode
+
+To force the macOS app to **never install or manage launchd**, launch it with
+`--attach-only` (or `--no-launchd`). This sets `~/.nodmix/disable-launchagent`,
+so the app only attaches to an already running Gateway. You can toggle the same
+behavior in Debug Settings.
+
+## Remote mode
+
+Remote mode never starts a local Gateway. The app uses an SSH tunnel to the
+remote host and connects over that tunnel.
+
+## Why we prefer launchd
+
+- Auto-start at login.
+- Built-in restart/KeepAlive semantics.
+- Predictable logs and supervision.
+
+If a true child-process mode is ever needed again, it should be documented as a
+separate, explicit dev-only mode.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway runbook](/gateway)