clawdie-iso/README.md

Clawdie ISO

Unified installer for Clawdie-AI on FreeBSD — baremetal and VPS

A single-step deployment platform with two targets:

• --target baremetal — Lumina desktop + Wayland + full operator UI
• --target vps — headless + Wayland (cage) for browser automation

Both targets include Tailscale (mandatory), PF firewall, and the glasspane remote operator stack.

Standing on the shoulders of giants: FreeBSD, PC-BSD's Lumina, Tailscale, proven shell patterns.

---

Pre-Install Requirements

Before building or booting:

1. Tailscale account — free up to 100 devices: https://tailscale.com
2. Auth key — generate at Tailscale admin console → Settings → Keys → Auth Keys
   • Check "Reusable" if deploying multiple instances
3. Have the key ready: tskey-auth-...

Tailscale is mandatory. It is the security perimeter. PF blocks SSH and VNC on the public interface — access is via tailscale0 only. See NETWORKING.md for details.

---

What You Get

Boot a USB, answer a 3-screen wizard, one reboot:

• ✅ Tailscale connected (secure remote access from first boot)
• ✅ PF firewall (brute-force protected, Tailscale-gated)
• ✅ Bastille jails (worker, db, cms) provisioned
• ✅ PostgreSQL + pgvector seeded
• ✅ Clawdie-AI agent running
• ✅ Glasspane: SSH → tmux panes + wayvnc → cage → Chromium
• ✅ All offline (no internet required during install, Tailscale auth aside)

Baremetal adds:

• ✅ Lumina desktop (ready to use)
• ✅ Admin panel accessible from taskbar

One reboot. That's it.

---

Quick Start

Build the USB Image

# Requirements: FreeBSD 15.0+, pkg, curl, 64 GB USB key, Tailscale auth key

git clone https://codeberg.org/Clawdie/Clawdie-ISO.git
cd Clawdie-ISO

# Set your Tailscale auth key
export TAILSCALE_AUTHKEY="tskey-auth-..."

# Fetch FreeBSD memstick + all packages (non-root)
./build.sh --fetch-only

# Assemble ISO (requires root)
sudo ./build.sh --skip-fetch

# Output: tmp/output/clawdie-iso-unified-DD.mmm.YYYY.img (~50 GB)

Install on Hardware

1. Write to USB:

   sudo dd if=tmp/output/clawdie-iso-unified-DD.mmm.YYYY.img of=/dev/da0 bs=1M status=progress
   sudo sync
   

2. Boot from USB, run bsdinstall (choose disk, root password, create clawdie user)

3. First boot from HDD:

   • Wizard screen 1: Tailscale auth key (pre-filled if baked into build.cfg)
   • Wizard screen 2: Assistant name + domain
   • Wizard screen 3: Timezone
   • Optional: LLM provider, Telegram
   • Setup runs automatically (5–10 min)

4. Desktop boots (if display detected) or headless mode (VPS/cloud)

   • Glasspane: ssh clawdie@<tailscale-ip> → tmux
   • Glasspane visual: connect wayvnc on <tailscale-ip>:5900

---

Documentation

• BUILD.md — Build instructions and flags
• NETWORKING.md — PF firewall, Tailscale, glasspane
• PLAN-UNIFY.md — In-progress: unification from clawdie-shell (see for next steps)
• SHELL-ARCHITECTURE.md — Shell module architecture
• SHELL-MODULES.md — Module reference
• LUMINA-INTEGRATION.md — Desktop configuration (baremetal)
• ADMIN-PANEL.md — Admin UI specification (baremetal)
• TESTING.md — Test procedures

---

Philosophy: Standing on Giants' Shoulders

Giant	Contribution
FreeBSD	ZFS, jails, rc.d, pkg, stability
PC-BSD	Lumina desktop, installer patterns
Tailscale	Zero-config secure networking
POSIX shell	Portability, simplicity, proven patterns
bsddialog	Native FreeBSD UI (no GTK/Qt bloat)
Bastille	Jail orchestration

---

Features

Glasspane (Remote Operator Access)

Both targets ship with the full glasspane stack:

Operator → Tailscale → SSH → tmux      (watch agent terminal panes)
Operator → Tailscale → wayvnc:5900 → cage → Chromium  (watch browser automation)

PF enforces Tailscale-only access. Public SSH and VNC ports are blocked.

Shell Modules

Modular, POSIX-compliant, testable:

• shell-env.sh — Identity + secrets
• shell-pkg.sh — Package repositories
• shell-gpu.sh — GPU detection
• shell-system.sh — System config
• shell-deploy.sh — AI setup + jails
• shell-tailscale.sh — Tailscale setup (mandatory)
• shell-pf.sh — PF firewall + brute-force protection (in progress)

Targets

Feature	VPS	Baremetal
Tailscale	mandatory	mandatory
PF firewall	yes	yes
cage + wayvnc (glasspane)	yes	yes
Lumina desktop	no	yes
Admin panel	no	yes
bsddialog wizard	no (baked config)	yes

Offline-First

• All packages bundled on USB
• Reproducible deploys
• Falls back to online if connected

---

System Requirements

• CPU: 2 cores (4 recommended)
• RAM: 4 GB (8 GB recommended)
• Disk: 50 GB
• GPU: Intel, AMD, NVIDIA, or VESA fallback
• Tailscale auth key — required (free tier covers 100 devices)

---

Version History

• v0.2.0 (23.mar.2026) — Initial ISO branding, Lumina, modular architecture
• v0.3.0 (24.mar.2026) — Community feedback: recovery, POSIX, security, audio
• v0.4.0 (27.mar.2026) — PF firewall, brute-force protection, pf_reload race fix
• v0.5.0 (in progress) — Mandatory Tailscale, glasspane, --target flag, repo unification
• v1.0.0 (planned) — Stable release after hardware testing

---

Known Limitations

• Single desktop: Lumina only (baremetal target)
• Interactive baremetal deployment (no cloud-init; VPS uses pre-baked config)
• Wayland (cage) available; full Wayland desktop not yet (X11 + cage hybrid)

---

Contributing

• Issues: Codeberg Issues
• Philosophy: Secure by default, opinionated where it matters, inherit don't reinvent.

---

Last updated: 06.apr.2026 Standing on: FreeBSD, Lumina, PC-BSD wisdom, Tailscale