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

5. Install rustup (needed for native builds like SWC/tree-sitter):

   sudo mkdir -p /opt/clawdie/tmp /opt/clawdie/rustup /opt/clawdie/cargo
   sudo fetch -o /opt/clawdie/tmp/rustup-init.sh https://sh.rustup.rs
   sudo env RUSTUP_HOME=/opt/clawdie/rustup CARGO_HOME=/opt/clawdie/cargo \
     sh /opt/clawdie/tmp/rustup-init.sh -y --profile minimal --default-toolchain stable
   

---

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-nvidia.sh — NVIDIA driver selection + install
• shell-ssh.sh — SSH keys + passwords
• shell-system.sh — System config
• shell-desktop.sh — Desktop enablement
• shell-pf.sh — PF firewall + brute-force protection
• shell-tailscale.sh — Tailscale setup (mandatory)
• shell-npm-globals.sh — Bundled npm CLIs (claude/gemini/pi)
• shell-zfs.sh — ZFS pool detection
• shell-deploy.sh — AI setup + jails

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
• v0.9.0 (6.apr.2026) — Phase 1-4 QML installer complete, Phase 4 blockers fixed, full ISO build verified
• v1.0.0 (ready for testing) — Stable release after hardware testing (see PHASE4-TEST-REPORT-06.APR.2026.md)

---

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