milaidy 1.0.0

package/docs/platforms/oracle.md

@@ -0,0 +1,303 @@
+---
+summary: "Milaidy on Oracle Cloud (Always Free ARM)"
+read_when:
+  - Setting up Milaidy on Oracle Cloud
+  - Looking for low-cost VPS hosting for Milaidy
+  - Want 24/7 Milaidy on a small server
+title: "Oracle Cloud"
+---
+
+# Milaidy on Oracle Cloud (OCI)
+
+## Goal
+
+Run a persistent Milaidy Gateway on Oracle Cloud's **Always Free** ARM tier.
+
+Oracle’s free tier can be a great fit for Milaidy (especially if you already have an OCI account), but it comes with tradeoffs:
+
+- ARM architecture (most things work, but some binaries may be x86-only)
+- Capacity and signup can be finicky
+
+## Cost Comparison (2026)
+
+| Provider     | Plan            | Specs                  | Price/mo | Notes                 |
+| ------------ | --------------- | ---------------------- | -------- | --------------------- |
+| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0       | ARM, limited capacity |
+| Hetzner      | CX22            | 2 vCPU, 4GB RAM        | ~ $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    |
+
+---
+
+## Prerequisites
+
+- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) — see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues
+- Tailscale account (free at [tailscale.com](https://tailscale.com))
+- ~30 minutes
+
+## 1) Create an OCI Instance
+
+1. Log into [Oracle Cloud Console](https://cloud.oracle.com/)
+2. Navigate to **Compute → Instances → Create Instance**
+3. Configure:
+   - **Name:** `milaidy`
+   - **Image:** Ubuntu 24.04 (aarch64)
+   - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM)
+   - **OCPUs:** 2 (or up to 4)
+   - **Memory:** 12 GB (or up to 24 GB)
+   - **Boot volume:** 50 GB (up to 200 GB free)
+   - **SSH key:** Add your public key
+4. Click **Create**
+5. Note the public IP address
+
+**Tip:** If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.
+
+## 2) Connect and Update
+
+```bash
+# Connect via public IP
+ssh ubuntu@YOUR_PUBLIC_IP
+
+# Update system
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y build-essential
+```
+
+**Note:** `build-essential` is required for ARM compilation of some dependencies.
+
+## 3) Configure User and Hostname
+
+```bash
+# Set hostname
+sudo hostnamectl set-hostname milaidy
+
+# Set password for ubuntu user
+sudo passwd ubuntu
+
+# Enable lingering (keeps user services running after logout)
+sudo loginctl enable-linger ubuntu
+```
+
+## 4) Install Tailscale
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up --ssh --hostname=milaidy
+```
+
+This enables Tailscale SSH, so you can connect via `ssh milaidy` from any device on your tailnet — no public IP needed.
+
+Verify:
+
+```bash
+tailscale status
+```
+
+**From now on, connect via Tailscale:** `ssh ubuntu@milaidy` (or use the Tailscale IP).
+
+## 5) Install Milaidy
+
+```bash
+curl -fsSL https://milaidy.ai/install.sh | bash
+source ~/.bashrc
+```
+
+When prompted "How do you want to hatch your bot?", select **"Do this later"**.
+
+> Note: If you hit ARM-native build issues, start with system packages (e.g. `sudo apt install -y build-essential`) before reaching for Homebrew.
+
+## 6) Configure Gateway (loopback + token auth) and enable Tailscale Serve
+
+Use token auth as the default. It’s predictable and avoids needing any “insecure auth” Control UI flags.
+
+```bash
+# Keep the Gateway private on the VM
+milaidy config set gateway.bind loopback
+
+# Require auth for the Gateway + Control UI
+milaidy config set gateway.auth.mode token
+milaidy doctor --generate-gateway-token
+
+# Expose over Tailscale Serve (HTTPS + tailnet access)
+milaidy config set gateway.tailscale.mode serve
+milaidy config set gateway.trustedProxies '["127.0.0.1"]'
+
+systemctl --user restart milaidy-gateway
+```
+
+## 7) Verify
+
+```bash
+# Check version
+milaidy --version
+
+# Check daemon status
+systemctl --user status milaidy-gateway
+
+# Check Tailscale Serve
+tailscale serve status
+
+# Test local response
+curl http://localhost:18789
+```
+
+## 8) Lock Down VCN Security
+
+Now that everything is working, lock down the VCN to block all traffic except Tailscale. OCI's Virtual Cloud Network acts as a firewall at the network edge — traffic is blocked before it reaches your instance.
+
+1. Go to **Networking → Virtual Cloud Networks** in the OCI Console
+2. Click your VCN → **Security Lists** → Default Security List
+3. **Remove** all ingress rules except:
+   - `0.0.0.0/0 UDP 41641` (Tailscale)
+4. Keep default egress rules (allow all outbound)
+
+This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. From now on, you can only connect via Tailscale.
+
+---
+
+## Access the Control UI
+
+From any device on your Tailscale network:
+
+```
+https://milaidy.<tailnet-name>.ts.net/
+```
+
+Replace `<tailnet-name>` with your tailnet name (visible in `tailscale status`).
+
+No SSH tunnel needed. Tailscale provides:
+
+- HTTPS encryption (automatic certs)
+- Authentication via Tailscale identity
+- Access from any device on your tailnet (laptop, phone, etc.)
+
+---
+
+## Security: VCN + Tailscale (recommended baseline)
+
+With the VCN locked down (only UDP 41641 open) and the Gateway bound to loopback, you get strong defense-in-depth: public traffic is blocked at the network edge, and admin access happens over your tailnet.
+
+This setup often removes the _need_ for extra host-based firewall rules purely to stop Internet-wide SSH brute force — but you should still keep the OS updated, run `milaidy security audit`, and verify you aren’t accidentally listening on public interfaces.
+
+### What's Already Protected
+
+| Traditional Step   | Needed?     | Why                                                                          |
+| ------------------ | ----------- | ---------------------------------------------------------------------------- |
+| UFW firewall       | No          | VCN blocks before traffic reaches instance                                   |
+| fail2ban           | No          | No brute force if port 22 blocked at VCN                                     |
+| sshd hardening     | No          | Tailscale SSH doesn't use sshd                                               |
+| Disable root login | No          | Tailscale uses Tailscale identity, not system users                          |
+| SSH key-only auth  | No          | Tailscale authenticates via your tailnet                                     |
+| IPv6 hardening     | Usually not | Depends on your VCN/subnet settings; verify what’s actually assigned/exposed |
+
+### Still Recommended
+
+- **Credential permissions:** `chmod 700 ~/.milaidy`
+- **Security audit:** `milaidy security audit`
+- **System updates:** `sudo apt update && sudo apt upgrade` regularly
+- **Monitor Tailscale:** Review devices in [Tailscale admin console](https://login.tailscale.com/admin)
+
+### Verify Security Posture
+
+```bash
+# Confirm no public ports listening
+sudo ss -tlnp | grep -v '127.0.0.1\|::1'
+
+# Verify Tailscale SSH is active
+tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active"
+
+# Optional: disable sshd entirely
+sudo systemctl disable --now ssh
+```
+
+---
+
+## Fallback: SSH Tunnel
+
+If Tailscale Serve isn't working, use an SSH tunnel:
+
+```bash
+# From your local machine (via Tailscale)
+ssh -L 18789:127.0.0.1:18789 ubuntu@milaidy
+```
+
+Then open `http://localhost:18789`.
+
+---
+
+## Troubleshooting
+
+### Instance creation fails ("Out of capacity")
+
+Free tier ARM instances are popular. Try:
+
+- Different availability domain
+- Retry during off-peak hours (early morning)
+- Use the "Always Free" filter when selecting shape
+
+### Tailscale won't connect
+
+```bash
+# Check status
+sudo tailscale status
+
+# Re-authenticate
+sudo tailscale up --ssh --hostname=milaidy --reset
+```
+
+### Gateway won't start
+
+```bash
+milaidy gateway status
+milaidy doctor --non-interactive
+journalctl --user -u milaidy-gateway -n 50
+```
+
+### Can't reach Control UI
+
+```bash
+# Verify Tailscale Serve is running
+tailscale serve status
+
+# Check gateway is listening
+curl http://localhost:18789
+
+# Restart if needed
+systemctl --user restart milaidy-gateway
+```
+
+### ARM binary issues
+
+Some tools may not have ARM builds. Check:
+
+```bash
+uname -m  # Should show aarch64
+```
+
+Most npm packages work fine. For binaries, look for `linux-arm64` or `aarch64` releases.
+
+---
+
+## Persistence
+
+All state lives in:
+
+- `~/.milaidy/` — config, credentials, session data
+- `~/.milaidy/workspace/` — workspace (AGENTS.md, memory, artifacts)
+
+Back up periodically:
+
+```bash
+tar -czvf milaidy-backup.tar.gz ~/.milaidy ~/.milaidy/workspace
+```
+
+---
+
+## See Also
+
+- [Gateway remote access](/gateway/remote) — other remote access patterns
+- [Tailscale integration](/gateway/tailscale) — full Tailscale docs
+- [Gateway configuration](/gateway/configuration) — all config options
+- [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup
+- [Hetzner guide](/platforms/hetzner) — Docker-based alternative

package/docs/platforms/raspberry-pi.md

@@ -0,0 +1,358 @@
+---
+summary: "Milaidy on Raspberry Pi (budget self-hosted setup)"
+read_when:
+  - Setting up Milaidy on a Raspberry Pi
+  - Running Milaidy on ARM devices
+  - Building a cheap always-on personal AI
+title: "Raspberry Pi"
+---
+
+# Milaidy on Raspberry Pi
+
+## Goal
+
+Run a persistent, always-on Milaidy Gateway on a Raspberry Pi for **~$35-80** one-time cost (no monthly fees).
+
+Perfect for:
+
+- 24/7 personal AI assistant
+- Home automation hub
+- Low-power, always-available Telegram/WhatsApp bot
+
+## Hardware Requirements
+
+| Pi Model        | RAM     | Works?   | Notes                              |
+| --------------- | ------- | -------- | ---------------------------------- |
+| **Pi 5**        | 4GB/8GB | ✅ Best  | Fastest, recommended               |
+| **Pi 4**        | 4GB     | ✅ Good  | Sweet spot for most users          |
+| **Pi 4**        | 2GB     | ✅ OK    | Works, add swap                    |
+| **Pi 4**        | 1GB     | ⚠️ Tight | Possible with swap, minimal config |
+| **Pi 3B+**      | 1GB     | ⚠️ Slow  | Works but sluggish                 |
+| **Pi Zero 2 W** | 512MB   | ❌       | Not recommended                    |
+
+**Minimum specs:** 1GB RAM, 1 core, 500MB disk  
+**Recommended:** 2GB+ RAM, 64-bit OS, 16GB+ SD card (or USB SSD)
+
+## What You'll Need
+
+- Raspberry Pi 4 or 5 (2GB+ recommended)
+- MicroSD card (16GB+) or USB SSD (better performance)
+- Power supply (official Pi PSU recommended)
+- Network connection (Ethernet or WiFi)
+- ~30 minutes
+
+## 1) Flash the OS
+
+Use **Raspberry Pi OS Lite (64-bit)** — no desktop needed for a headless server.
+
+1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
+2. Choose OS: **Raspberry Pi OS Lite (64-bit)**
+3. Click the gear icon (⚙️) to pre-configure:
+   - Set hostname: `gateway-host`
+   - Enable SSH
+   - Set username/password
+   - Configure WiFi (if not using Ethernet)
+4. Flash to your SD card / USB drive
+5. Insert and boot the Pi
+
+## 2) Connect via SSH
+
+```bash
+ssh user@gateway-host
+# or use the IP address
+ssh user@192.168.x.x
+```
+
+## 3) System Setup
+
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install essential packages
+sudo apt install -y git curl build-essential
+
+# Set timezone (important for cron/reminders)
+sudo timedatectl set-timezone America/Chicago  # Change to your timezone
+```
+
+## 4) Install Node.js 22 (ARM64)
+
+```bash
+# Install Node.js via NodeSource
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Verify
+node --version  # Should show v22.x.x
+npm --version
+```
+
+## 5) Add Swap (Important for 2GB or less)
+
+Swap prevents out-of-memory crashes:
+
+```bash
+# Create 2GB swap file
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+
+# Make permanent
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+
+# Optimize for low RAM (reduce swappiness)
+echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+## 6) Install Milaidy
+
+### Option A: Standard Install (Recommended)
+
+```bash
+curl -fsSL https://milaidy.ai/install.sh | bash
+```
+
+### Option B: Hackable Install (For tinkering)
+
+```bash
+git clone https://github.com/milaidy/milaidy.git
+cd milaidy
+npm install
+npm run build
+npm link
+```
+
+The hackable install gives you direct access to logs and code — useful for debugging ARM-specific issues.
+
+## 7) Run Onboarding
+
+```bash
+milaidy onboard --install-daemon
+```
+
+Follow the wizard:
+
+1. **Gateway mode:** Local
+2. **Auth:** API keys recommended (OAuth can be finicky on headless Pi)
+3. **Channels:** Telegram is easiest to start with
+4. **Daemon:** Yes (systemd)
+
+## 8) Verify Installation
+
+```bash
+# Check status
+milaidy status
+
+# Check service
+sudo systemctl status milaidy
+
+# View logs
+journalctl -u milaidy -f
+```
+
+## 9) Access the Dashboard
+
+Since the Pi is headless, use an SSH tunnel:
+
+```bash
+# From your laptop/desktop
+ssh -L 18789:localhost:18789 user@gateway-host
+
+# Then open in browser
+open http://localhost:18789
+```
+
+Or use Tailscale for always-on access:
+
+```bash
+# On the Pi
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+
+# Update config
+milaidy config set gateway.bind tailnet
+sudo systemctl restart milaidy
+```
+
+---
+
+## Performance Optimizations
+
+### Use a USB SSD (Huge Improvement)
+
+SD cards are slow and wear out. A USB SSD dramatically improves performance:
+
+```bash
+# Check if booting from USB
+lsblk
+```
+
+See [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot) for setup.
+
+### Reduce Memory Usage
+
+```bash
+# Disable GPU memory allocation (headless)
+echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
+
+# Disable Bluetooth if not needed
+sudo systemctl disable bluetooth
+```
+
+### Monitor Resources
+
+```bash
+# Check memory
+free -h
+
+# Check CPU temperature
+vcgencmd measure_temp
+
+# Live monitoring
+htop
+```
+
+---
+
+## ARM-Specific Notes
+
+### Binary Compatibility
+
+Most Milaidy features work on ARM64, but some external binaries may need ARM builds:
+
+| Tool               | ARM64 Status | Notes                               |
+| ------------------ | ------------ | ----------------------------------- |
+| Node.js            | ✅           | Works great                         |
+| WhatsApp (Baileys) | ✅           | Pure JS, no issues                  |
+| Telegram           | ✅           | Pure JS, no issues                  |
+| gog (Gmail CLI)    | ⚠️           | Check for ARM release               |
+| Chromium (browser) | ✅           | `sudo apt install chromium-browser` |
+
+If a skill fails, check if its binary has an ARM build. Many Go/Rust tools do; some don't.
+
+### 32-bit vs 64-bit
+
+**Always use 64-bit OS.** Node.js and many modern tools require it. Check with:
+
+```bash
+uname -m
+# Should show: aarch64 (64-bit) not armv7l (32-bit)
+```
+
+---
+
+## Recommended Model Setup
+
+Since the Pi is just the Gateway (models run in the cloud), use API-based models:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-sonnet-4-20250514",
+        "fallbacks": ["openai/gpt-5-mini"]
+      }
+    }
+  }
+}
+```
+
+**Don't try to run local LLMs on a Pi** — even small models are too slow. Let Claude/GPT do the heavy lifting.
+
+---
+
+## Auto-Start on Boot
+
+The onboarding wizard sets this up, but to verify:
+
+```bash
+# Check service is enabled
+sudo systemctl is-enabled milaidy
+
+# Enable if not
+sudo systemctl enable milaidy
+
+# Start on boot
+sudo systemctl start milaidy
+```
+
+---
+
+## Troubleshooting
+
+### Out of Memory (OOM)
+
+```bash
+# Check memory
+free -h
+
+# Add more swap (see Step 5)
+# Or reduce services running on the Pi
+```
+
+### Slow Performance
+
+- Use USB SSD instead of SD card
+- Disable unused services: `sudo systemctl disable cups bluetooth avahi-daemon`
+- Check CPU throttling: `vcgencmd get_throttled` (should return `0x0`)
+
+### Service Won't Start
+
+```bash
+# Check logs
+journalctl -u milaidy --no-pager -n 100
+
+# Common fix: rebuild
+cd ~/milaidy  # if using hackable install
+npm run build
+sudo systemctl restart milaidy
+```
+
+### ARM Binary Issues
+
+If a skill fails with "exec format error":
+
+1. Check if the binary has an ARM64 build
+2. Try building from source
+3. Or use a Docker container with ARM support
+
+### WiFi Drops
+
+For headless Pis on WiFi:
+
+```bash
+# Disable WiFi power management
+sudo iwconfig wlan0 power off
+
+# Make permanent
+echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
+```
+
+---
+
+## Cost Comparison
+
+| Setup          | One-Time Cost | Monthly Cost | Notes                     |
+| -------------- | ------------- | ------------ | ------------------------- |
+| **Pi 4 (2GB)** | ~$45          | $0           | + power (~$5/yr)          |
+| **Pi 4 (4GB)** | ~$55          | $0           | Recommended               |
+| **Pi 5 (4GB)** | ~$60          | $0           | Best performance          |
+| **Pi 5 (8GB)** | ~$80          | $0           | Overkill but future-proof |
+| DigitalOcean   | $0            | $6/mo        | $72/year                  |
+| Hetzner        | $0            | €3.79/mo     | ~$50/year                 |
+
+**Break-even:** A Pi pays for itself in ~6-12 months vs cloud VPS.
+
+---
+
+## See Also
+
+- [Linux guide](/platforms/linux) — general Linux setup
+- [DigitalOcean guide](/platforms/digitalocean) — cloud alternative
+- [Hetzner guide](/platforms/hetzner) — Docker setup
+- [Tailscale](/gateway/tailscale) — remote access
+- [Nodes](/nodes) — pair your laptop/phone with the Pi gateway