milaidy 1.0.0

package/docs/platforms/android.md

@@ -0,0 +1,129 @@
+---
+summary: "Android app (node): connection runbook + Canvas/Chat/Camera"
+read_when:
+  - Pairing or reconnecting the Android node
+  - Debugging Android gateway discovery or auth
+  - Verifying chat history parity across clients
+title: "Android App"
+---
+
+# Android App (Node)
+
+## Support snapshot
+
+- Role: companion node app (Android does not host the Gateway).
+- Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
+- Install: [Getting Started](/start/getting-started) + [Pairing](/gateway/pairing).
+- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
+  - Protocols: [Gateway protocol](/gateway/protocol) (nodes + control plane).
+
+## System control
+
+System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
+
+## Connection Runbook
+
+Android node app ⇄ (mDNS/NSD + WebSocket) ⇄ **Gateway**
+
+Android connects directly to the Gateway WebSocket (default `ws://<host>:18789`) and uses Gateway-owned pairing.
+
+### Prerequisites
+
+- You can run the Gateway on the “master” machine.
+- Android device/emulator can reach the gateway WebSocket:
+  - Same LAN with mDNS/NSD, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual gateway host/port (fallback)
+- You can run the CLI (`milaidy`) on the gateway machine (or via SSH).
+
+### 1) Start the Gateway
+
+```bash
+milaidy gateway --port 18789 --verbose
+```
+
+Confirm in logs you see something like:
+
+- `listening on ws://0.0.0.0:18789`
+
+For tailnet-only setups (recommended for Vienna ⇄ London), bind the gateway to the tailnet IP:
+
+- Set `gateway.bind: "tailnet"` in `~/.milaidy/milaidy.json` on the gateway host.
+- Restart the Gateway / macOS menubar app.
+
+### 2) Verify discovery (optional)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _milaidy-gw._tcp local.
+```
+
+More debugging notes: [Bonjour](/gateway/bonjour).
+
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
+
+1. Set up a DNS-SD zone (example `milaidy.internal.`) on the gateway host and publish `_milaidy-gw._tcp` records.
+2. Configure Tailscale split DNS for your chosen domain pointing at that DNS server.
+
+Details and example CoreDNS config: [Bonjour](/gateway/bonjour).
+
+### 3) Connect from Android
+
+In the Android app:
+
+- The app keeps its gateway connection alive via a **foreground service** (persistent notification).
+- Open **Settings**.
+- Under **Discovered Gateways**, select your gateway and hit **Connect**.
+- If mDNS is blocked, use **Advanced → Manual Gateway** (host + port) and **Connect (Manual)**.
+
+After the first successful pairing, Android auto-reconnects on launch:
+
+- Manual endpoint (if enabled), otherwise
+- The last discovered gateway (best-effort).
+
+### 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+milaidy nodes pending
+milaidy nodes approve <requestId>
+```
+
+Pairing details: [Gateway pairing](/gateway/pairing).
+
+### 5) Verify the node is connected
+
+- Via nodes status:
+  ```bash
+  milaidy nodes status
+  ```
+- Via Gateway:
+  ```bash
+  milaidy gateway call node.list --params "{}"
+  ```
+
+### 6) Chat + history
+
+The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
+
+- History: `chat.history`
+- Send: `chat.send`
+- Push updates (best-effort): `chat.subscribe` → `event:"chat"`
+
+### 7) Canvas + camera
+
+Canvas commands (foreground only):
+
+- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
+- A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias)
+
+Camera commands (foreground only; permission-gated):
+
+- `camera.snap` (jpg)
+- `camera.clip` (mp4)
+
+See [Camera node](/nodes/camera) for parameters and CLI helpers.

package/docs/platforms/digitalocean.md

@@ -0,0 +1,262 @@
+---
+summary: "Milaidy on DigitalOcean (simple paid VPS option)"
+read_when:
+  - Setting up Milaidy on DigitalOcean
+  - Looking for cheap VPS hosting for Milaidy
+title: "DigitalOcean"
+---
+
+# Milaidy on DigitalOcean
+
+## Goal
+
+Run a persistent Milaidy Gateway on DigitalOcean for **$6/month** (or $4/mo with reserved pricing).
+
+If you want a $0/month option and don’t mind ARM + provider-specific setup, see the [Oracle Cloud guide](/platforms/oracle).
+
+## Cost Comparison (2026)
+
+| Provider     | Plan            | Specs                  | Price/mo    | Notes                                 |
+| ------------ | --------------- | ---------------------- | ----------- | ------------------------------------- |
+| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0          | ARM, limited capacity / signup quirks |
+| Hetzner      | CX22            | 2 vCPU, 4GB RAM        | €3.79 (~$4) | Cheapest paid option                  |
+| DigitalOcean | Basic           | 1 vCPU, 1GB RAM        | $6          | Easy UI, good docs                    |
+| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM        | $6          | Many locations                        |
+| Linode       | Nanode          | 1 vCPU, 1GB RAM        | $5          | Now part of Akamai                    |
+
+**Picking a provider:**
+
+- DigitalOcean: simplest UX + predictable setup (this guide)
+- Hetzner: good price/perf (see [Hetzner guide](/platforms/hetzner))
+- Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle))
+
+---
+
+## Prerequisites
+
+- DigitalOcean account ([signup with $200 free credit](https://m.do.co/c/signup))
+- SSH key pair (or willingness to use password auth)
+- ~20 minutes
+
+## 1) Create a Droplet
+
+1. Log into [DigitalOcean](https://cloud.digitalocean.com/)
+2. Click **Create → Droplets**
+3. Choose:
+   - **Region:** Closest to you (or your users)
+   - **Image:** Ubuntu 24.04 LTS
+   - **Size:** Basic → Regular → **$6/mo** (1 vCPU, 1GB RAM, 25GB SSD)
+   - **Authentication:** SSH key (recommended) or password
+4. Click **Create Droplet**
+5. Note the IP address
+
+## 2) Connect via SSH
+
+```bash
+ssh root@YOUR_DROPLET_IP
+```
+
+## 3) Install Milaidy
+
+```bash
+# Update system
+apt update && apt upgrade -y
+
+# Install Node.js 22
+curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+apt install -y nodejs
+
+# Install Milaidy
+curl -fsSL https://milaidy.ai/install.sh | bash
+
+# Verify
+milaidy --version
+```
+
+## 4) Run Onboarding
+
+```bash
+milaidy onboard --install-daemon
+```
+
+The wizard will walk you through:
+
+- Model auth (API keys or OAuth)
+- Channel setup (Telegram, WhatsApp, Discord, etc.)
+- Gateway token (auto-generated)
+- Daemon installation (systemd)
+
+## 5) Verify the Gateway
+
+```bash
+# Check status
+milaidy status
+
+# Check service
+systemctl --user status milaidy-gateway.service
+
+# View logs
+journalctl --user -u milaidy-gateway.service -f
+```
+
+## 6) Access the Dashboard
+
+The gateway binds to loopback by default. To access the Control UI:
+
+**Option A: SSH Tunnel (recommended)**
+
+```bash
+# From your local machine
+ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
+
+# Then open: http://localhost:18789
+```
+
+**Option B: Tailscale Serve (HTTPS, loopback-only)**
+
+```bash
+# On the droplet
+curl -fsSL https://tailscale.com/install.sh | sh
+tailscale up
+
+# Configure Gateway to use Tailscale Serve
+milaidy config set gateway.tailscale.mode serve
+milaidy gateway restart
+```
+
+Open: `https://<magicdns>/`
+
+Notes:
+
+- Serve keeps the Gateway loopback-only and authenticates via Tailscale identity headers.
+- To require token/password instead, set `gateway.auth.allowTailscale: false` or use `gateway.auth.mode: "password"`.
+
+**Option C: Tailnet bind (no Serve)**
+
+```bash
+milaidy config set gateway.bind tailnet
+milaidy gateway restart
+```
+
+Open: `http://<tailscale-ip>:18789` (token required).
+
+## 7) Connect Your Channels
+
+### Telegram
+
+```bash
+milaidy pairing list telegram
+milaidy pairing approve telegram <CODE>
+```
+
+### WhatsApp
+
+```bash
+milaidy channels login whatsapp
+# Scan QR code
+```
+
+See [Channels](/channels) for other providers.
+
+---
+
+## Optimizations for 1GB RAM
+
+The $6 droplet only has 1GB RAM. To keep things running smoothly:
+
+### Add swap (recommended)
+
+```bash
+fallocate -l 2G /swapfile
+chmod 600 /swapfile
+mkswap /swapfile
+swapon /swapfile
+echo '/swapfile none swap sw 0 0' >> /etc/fstab
+```
+
+### Use a lighter model
+
+If you're hitting OOMs, consider:
+
+- Using API-based models (Claude, GPT) instead of local models
+- Setting `agents.defaults.model.primary` to a smaller model
+
+### Monitor memory
+
+```bash
+free -h
+htop
+```
+
+---
+
+## Persistence
+
+All state lives in:
+
+- `~/.milaidy/` — config, credentials, session data
+- `~/.milaidy/workspace/` — workspace (AGENTS.md, memory, etc.)
+
+These survive reboots. Back them up periodically:
+
+```bash
+tar -czvf milaidy-backup.tar.gz ~/.milaidy ~/.milaidy/workspace
+```
+
+---
+
+## Oracle Cloud Free Alternative
+
+Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful than any paid option here — for $0/month.
+
+| What you get      | Specs                  |
+| ----------------- | ---------------------- |
+| **4 OCPUs**       | ARM Ampere A1          |
+| **24GB RAM**      | More than enough       |
+| **200GB storage** | Block volume           |
+| **Forever free**  | No credit card charges |
+
+**Caveats:**
+
+- Signup can be finicky (retry if it fails)
+- ARM architecture — most things work, but some binaries need ARM builds
+
+For the full setup guide, see [Oracle Cloud](/platforms/oracle). For signup tips and troubleshooting the enrollment process, see this [community guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd).
+
+---
+
+## Troubleshooting
+
+### Gateway won't start
+
+```bash
+milaidy gateway status
+milaidy doctor --non-interactive
+journalctl -u milaidy --no-pager -n 50
+```
+
+### Port already in use
+
+```bash
+lsof -i :18789
+kill <PID>
+```
+
+### Out of memory
+
+```bash
+# Check memory
+free -h
+
+# Add more swap
+# Or upgrade to $12/mo droplet (2GB RAM)
+```
+
+---
+
+## See Also
+
+- [Hetzner guide](/platforms/hetzner) — cheaper, more powerful
+- [Docker install](/install/docker) — containerized setup
+- [Tailscale](/gateway/tailscale) — secure remote access
+- [Configuration](/gateway/configuration) — full config reference

package/docs/platforms/exe-dev.md

@@ -0,0 +1,125 @@
+---
+summary: "Run Milaidy Gateway on exe.dev (VM + HTTPS proxy) for remote access"
+read_when:
+  - You want a cheap always-on Linux host for the Gateway
+  - You want remote Control UI access without running your own VPS
+title: "exe.dev"
+---
+
+# exe.dev
+
+Goal: Milaidy Gateway running on an exe.dev VM, reachable from your laptop via: `https://<vm-name>.exe.xyz`
+
+This page assumes exe.dev's default **exeuntu** image. If you picked a different distro, map packages accordingly.
+
+## Beginner quick path
+
+1. [https://exe.new/milaidy](https://exe.new/milaidy)
+2. Fill in your auth key/token as needed
+3. Click on "Agent" next to your VM, and wait...
+4. ???
+5. Profit
+
+## What you need
+
+- exe.dev account
+- `ssh exe.dev` access to [exe.dev](https://exe.dev) virtual machines (optional)
+
+## Automated Install with Shelley
+
+Shelley, [exe.dev](https://exe.dev)'s agent, can install Milaidy instantly with our
+prompt. The prompt used is as below:
+
+```
+Set up Milaidy (https://docs.milaidy.ai/install) on this VM. Use the non-interactive and accept-risk flags for milaidy onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "milaidy devices list" and "milaidy device approve <request id>". Make sure the dashboard shows that Milaidy's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be <vm-name>.exe.xyz, without port specification.
+```
+
+## Manual installation
+
+## 1) Create the VM
+
+From your device:
+
+```bash
+ssh exe.dev new
+```
+
+Then connect:
+
+```bash
+ssh <vm-name>.exe.xyz
+```
+
+Tip: keep this VM **stateful**. Milaidy stores state under `~/.milaidy/` and `~/.milaidy/workspace/`.
+
+## 2) Install prerequisites (on the VM)
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl jq ca-certificates openssl
+```
+
+## 3) Install Milaidy
+
+Run the Milaidy install script:
+
+```bash
+curl -fsSL https://milaidy.ai/install.sh | bash
+```
+
+## 4) Setup nginx to proxy Milaidy to port 8000
+
+Edit `/etc/nginx/sites-enabled/default` with
+
+```
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 8000;
+    listen [::]:8000;
+
+    server_name _;
+
+    location / {
+        proxy_pass http://127.0.0.1:18789;
+        proxy_http_version 1.1;
+
+        # WebSocket support
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Timeout settings for long-lived connections
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+    }
+}
+```
+
+## 5) Access Milaidy and grant privileges
+
+Access `https://<vm-name>.exe.xyz/?token=YOUR-TOKEN-FROM-TERMINAL` (see the Control UI output from onboarding). Approve
+devices with `milaidy devices list` and `milaidy devices approve <requestId>`. When in doubt,
+use Shelley from your browser!
+
+## Remote Access
+
+Remote access is handled by [exe.dev](https://exe.dev)'s authentication. By
+default, HTTP traffic from port 8000 is forwarded to `https://<vm-name>.exe.xyz`
+with email auth.
+
+## Updating
+
+```bash
+npm i -g milaidy@latest
+milaidy doctor
+milaidy gateway restart
+milaidy health
+```
+
+Guide: [Updating](/install/updating)