milaidy 1.0.0

package/docs/platforms/macos-vm.md

@@ -0,0 +1,281 @@
+---
+summary: "Run Milaidy in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage"
+read_when:
+  - You want Milaidy isolated from your main macOS environment
+  - You want iMessage integration (BlueBubbles) 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"
+---
+
+# Milaidy on macOS VMs (Sandboxing)
+
+## 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 (iMessage/BlueBubbles) or want strict isolation from your daily Mac.
+
+## macOS VM options
+
+### Local VM on your Apple Silicon Mac (Lume)
+
+Run Milaidy 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 BlueBubbles (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 milaidy --os macos --ipsw latest`
+3. Complete Setup Assistant, enable Remote Login (SSH)
+4. `lume run milaidy --no-display`
+5. SSH in, install Milaidy, 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 milaidy --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.
+
+---
+
+## 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's IP address
+
+```bash
+lume get milaidy
+```
+
+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 Milaidy
+
+Inside the VM:
+
+```bash
+npm install -g milaidy@latest
+milaidy 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 ~/.milaidy/milaidy.json
+```
+
+Add your channels:
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["+15551234567"]
+    },
+    "telegram": {
+      "botToken": "YOUR_BOT_TOKEN"
+    }
+  }
+}
+```
+
+Then login to WhatsApp (scan QR):
+
+```bash
+milaidy channels login
+```
+
+---
+
+## 8) Run the VM headlessly
+
+Stop the VM and restart without display:
+
+```bash
+lume stop milaidy
+lume run milaidy --no-display
+```
+
+The VM runs in the background. Milaidy's daemon keeps the gateway running.
+
+To check status:
+
+```bash
+ssh youruser@192.168.64.X "milaidy status"
+```
+
+---
+
+## Bonus: iMessage integration
+
+This is the killer feature of running on macOS. Use [BlueBubbles](https://bluebubbles.app) to add iMessage to Milaidy.
+
+Inside the VM:
+
+1. Download BlueBubbles from bluebubbles.app
+2. Sign in with your Apple ID
+3. Enable the Web API and set a password
+4. Point BlueBubbles webhooks at your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`)
+
+Add to your Milaidy config:
+
+```json
+{
+  "channels": {
+    "bluebubbles": {
+      "serverUrl": "http://localhost:1234",
+      "password": "your-api-password",
+      "webhookPath": "/bluebubbles-webhook"
+    }
+  }
+}
+```
+
+Restart the gateway. Now your agent can send and receive iMessages.
+
+Full setup details: [BlueBubbles channel](/channels/bluebubbles)
+
+---
+
+## Save a golden image
+
+Before customizing further, snapshot your clean state:
+
+```bash
+lume stop milaidy
+lume clone milaidy milaidy-golden
+```
+
+Reset anytime:
+
+```bash
+lume stop milaidy && lume delete milaidy
+lume clone milaidy-golden milaidy
+lume run milaidy --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 milaidy` 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 `milaidy channels login` |
+
+---
+
+## Related docs
+
+- [VPS hosting](/vps)
+- [Nodes](/nodes)
+- [Gateway remote](/gateway/remote)
+- [BlueBubbles channel](/channels/bluebubbles)
+- [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/platforms/macos.md

@@ -0,0 +1,203 @@
+---
+summary: "Milaidy macOS companion app (menu bar + gateway broker)"
+read_when:
+  - Implementing macOS app features
+  - Changing gateway lifecycle or node bridging on macOS
+title: "macOS App"
+---
+
+# Milaidy macOS Companion (menu bar + gateway broker)
+
+The macOS app is the **menu‑bar companion** for Milaidy. It owns permissions,
+manages/attaches to the Gateway locally (launchd or manual), and exposes macOS
+capabilities to the agent as a node.
+
+## What it does
+
+- Shows native notifications and status in the menu bar.
+- Owns TCC prompts (Notifications, Accessibility, Screen Recording, Microphone,
+  Speech Recognition, Automation/AppleScript).
+- Runs or connects to the Gateway (local or remote).
+- Exposes macOS‑only tools (Canvas, Camera, Screen Recording, `system.run`).
+- Starts the local node host service in **remote** mode (launchd), and stops it in **local** mode.
+- Optionally hosts **PeekabooBridge** for UI automation.
+- Installs the global CLI (`milaidy`) via npm/pnpm on request (bun not recommended for the Gateway runtime).
+
+## Local vs remote mode
+
+- **Local** (default): the app attaches to a running local Gateway if present;
+  otherwise it enables the launchd service via `milaidy gateway install`.
+- **Remote**: the app connects to a Gateway over SSH/Tailscale and never starts
+  a local process.
+  The app starts the local **node host service** so the remote Gateway can reach this Mac.
+  The app does not spawn the Gateway as a child process.
+
+## Launchd control
+
+The app manages a per‑user LaunchAgent labeled `bot.molt.gateway`
+(or `bot.molt.<profile>` when using `--profile`/`MILAIDY_PROFILE`; legacy `com.milaidy.*` still unloads).
+
+```bash
+launchctl kickstart -k gui/$UID/bot.molt.gateway
+launchctl bootout gui/$UID/bot.molt.gateway
+```
+
+Replace the label with `bot.molt.<profile>` when running a named profile.
+
+If the LaunchAgent isn’t installed, enable it from the app or run
+`milaidy gateway install`.
+
+## Node capabilities (mac)
+
+The macOS app presents itself as a node. Common commands:
+
+- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
+- Camera: `camera.snap`, `camera.clip`
+- Screen: `screen.record`
+- System: `system.run`, `system.notify`
+
+The node reports a `permissions` map so agents can decide what’s allowed.
+
+Node service + app IPC:
+
+- When the headless node host service is running (remote mode), it connects to the Gateway WS as a node.
+- `system.run` executes in the macOS app (UI/TCC context) over a local Unix socket; prompts + output stay in-app.
+
+Diagram (SCI):
+
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + TCC + system.run)
+```
+
+## Exec approvals (system.run)
+
+`system.run` is controlled by **Exec approvals** in the macOS app (Settings → Exec approvals).
+Security + ask + allowlist are stored locally on the Mac in:
+
+```
+~/.milaidy/exec-approvals.json
+```
+
+Example:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss"
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
+    }
+  }
+}
+```
+
+Notes:
+
+- `allowlist` entries are glob patterns for resolved binary paths.
+- Choosing “Always Allow” in the prompt adds that command to the allowlist.
+- `system.run` environment overrides are filtered (drops `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`) and then merged with the app’s environment.
+
+## Deep links
+
+The app registers the `milaidy://` URL scheme for local actions.
+
+### `milaidy://agent`
+
+Triggers a Gateway `agent` request.
+
+```bash
+open 'milaidy://agent?message=Hello%20from%20deep%20link'
+```
+
+Query parameters:
+
+- `message` (required)
+- `sessionKey` (optional)
+- `thinking` (optional)
+- `deliver` / `to` / `channel` (optional)
+- `timeoutSeconds` (optional)
+- `key` (optional unattended mode key)
+
+Safety:
+
+- Without `key`, the app prompts for confirmation.
+- With a valid `key`, the run is unattended (intended for personal automations).
+
+## Onboarding flow (typical)
+
+1. Install and launch **Milaidy.app**.
+2. Complete the permissions checklist (TCC prompts).
+3. Ensure **Local** mode is active and the Gateway is running.
+4. Install the CLI if you want terminal access.
+
+## Build & dev workflow (native)
+
+- `cd apps/macos && swift build`
+- `swift run Milaidy` (or Xcode)
+- Package app: `apps/shared/scripts/package-mac-app.sh`
+
+## Debug gateway connectivity (macOS CLI)
+
+Use the debug CLI to exercise the same Gateway WebSocket handshake and discovery
+logic that the macOS app uses, without launching the app.
+
+```bash
+cd apps/macos
+swift run milaidy-mac connect --json
+swift run milaidy-mac discover --timeout 3000 --json
+```
+
+Connect options:
+
+- `--url <ws://host:port>`: override config
+- `--mode <local|remote>`: resolve from config (default: config or local)
+- `--probe`: force a fresh health probe
+- `--timeout <ms>`: request timeout (default: `15000`)
+- `--json`: structured output for diffing
+
+Discovery options:
+
+- `--include-local`: include gateways that would be filtered as “local”
+- `--timeout <ms>`: overall discovery window (default: `2000`)
+- `--json`: structured output for diffing
+
+Tip: compare against `milaidy gateway discover --json` to see whether the
+macOS app’s discovery pipeline (NWBrowser + tailnet DNS‑SD fallback) differs from
+the Node CLI’s `dns-sd` based discovery.
+
+## Remote connection plumbing (SSH tunnels)
+
+When the macOS app runs in **Remote** mode, it opens an SSH tunnel so local UI
+components can talk to a remote Gateway as if it were on localhost.
+
+### Control tunnel (Gateway WebSocket port)
+
+- **Purpose:** health checks, status, Web Chat, config, and other control-plane calls.
+- **Local port:** the Gateway port (default `18789`), always stable.
+- **Remote port:** the same Gateway port on the remote host.
+- **Behavior:** no random local port; the app reuses an existing healthy tunnel
+  or restarts it if needed.
+- **SSH shape:** `ssh -N -L <local>:127.0.0.1:<remote>` with BatchMode +
+  ExitOnForwardFailure + keepalive options.
+- **IP reporting:** the SSH tunnel uses loopback, so the gateway will see the node
+  IP as `127.0.0.1`. Use **Direct (ws/wss)** transport if you want the real client
+  IP to appear (see [macOS remote access](/platforms/mac/remote)).
+
+For setup steps, see [macOS remote access](/platforms/mac/remote). For protocol
+details, see [Gateway protocol](/gateway/protocol).
+
+## Related docs
+
+- [Gateway runbook](/gateway)
+- [Gateway (macOS)](/platforms/mac/bundled-gateway)
+- [macOS permissions](/platforms/mac/permissions)
+- [Canvas](/platforms/mac/canvas)