clawdie-iso/docs/VPS-MIGRATION.md

Clawdie-VPS — Linux→FreeBSD Migration for VPS

Status: Ready for testing — 2026-03-18 Target: Vultr, Hetzner, OVH, any VPS with custom ISO support

---

Quick Start (Vultr)

Step 1: Upload mfsBSD ISO

1. Download mfsBSD ISO: https://depenguin.me/files/mfsbsd-15.0-RELEASE-amd64.iso
2. In Vultr panel: Server → Settings → Custom ISO → Upload ISO
3. Attach the ISO to your server
4. Reboot

Step 2: Boot and SSH

After reboot, the server boots into mfsBSD (FreeBSD in RAM):

ssh mfsbsd@<your-vps-ip>
# password: mfsroot

Step 3: Run Installer

fetch -o - https://clawdie.si/vps-setup.sh | sh

Or with custom config:

fetch -o setup.sh https://clawdie.si/vps-setup.sh
# Edit ASSISTANT_NAME, AGENT_DOMAIN, TZ at the top
vi setup.sh
sh setup.sh

Step 4: After Reboot

ssh clawdie@<your-vps-ip>
cd ~/clawdie-ai
npm run install-all

Done! Clawdie-AI is running on FreeBSD.

---

How It Works

Vultr VPS
  └─ Boot from mfsBSD ISO (FreeBSD in RAM)
       └─ SSH as mfsbsd
            └─ Run clawdie-vps-setup.sh
                 ├─ Partition disk (ZFS)
                 ├─ Install FreeBSD base
                 ├─ Configure system (users, network, TZ)
                 ├─ Install packages (node24, git, tmux, etc.)
                 ├─ Download Clawdie-AI from Codeberg
                 ├─ Generate secrets + .env
                 └─ Reboot

Final boot from HDD
  └─ FreeBSD + Clawdie-AI ready
       └─ Run: npm run install-all

---

Provider Support

Provider	Method	Difficulty	Notes
Vultr	Custom ISO	Easy ⭐	Upload mfsBSD ISO directly
Hetzner	Rescue + depenguin.me	Medium	Use depenguin.me script first
OVH	Rescue mode	Medium	Same as Hetzner
Hostinger	Check panel	Unknown	Look for ISO upload or rescue
DigitalOcean	Recovery console	Hard	No ISO support, use depenguin.me

---

Configuration Options

Edit these at the top of clawdie-vps-setup.sh:

Variable	Default	Description
ASSISTANT_NAME	Clawdie	Display name
AGENT_NAME	clawdie	System hostname (auto-derived)
AGENT_DOMAIN	clawdie.local	Domain name
TZ	UTC	Timezone (e.g., Europe/Ljubljana)
PI_PROVIDER	anthropic	LLM provider
CLAWDIE_VERSION	0.8.2	Clawdie-AI release

---

Files

clawdie-iso/vps/
├── clawdie-vps-setup.sh     ← Main installer (runs on mfsBSD)
├── clawdie-vps-migrate.sh   ← Linux→mfsBSD migration (for rescue mode)
├── clawdie.conf.tpl         ← Headless config template
└── firstboot-vps.sh         ← Alternative: interactive wizard

---

Security Notes

1. Change mfsBSD password after first SSH if concerned
2. All secrets auto-generated with 32-char random strings
3. .env mode 600 — only clawdie user can read
4. Wheel group has passwordless sudo — change if desired

---

Troubleshooting

SSH connection refused

• Wait 30-60 seconds after reboot for mfsBSD to start
• Check Vultr console for boot progress

Disk not detected

• Check with: sysctl kern.disks
• Manually set: DISK=/dev/da0 ./clawdie-vps-setup.sh

Install fails

• Check internet: fetch http://example.com
• Check logs in /var/log/install.log

---

Alternative: Build Custom ISO

For fully offline installs, you can build a custom mfsBSD ISO with Clawdie pre-bundled:

cd clawdie-iso
./build-vps.sh
# Output: tmp/output/clawdie-vps-DD.mmm.YYYY.iso

This requires more setup and is optional — the script approach above is simpler.