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

```bash
# 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:**
   ```bash
   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):
   ```bash
   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.md)** — Build instructions and flags
- **[NETWORKING.md](NETWORKING.md)** — PF firewall, Tailscale, glasspane
- **[PLAN-UNIFY.md](PLAN-UNIFY.md)** — In-progress: unification from clawdie-shell (see for next steps)
- **[SHELL-ARCHITECTURE.md](SHELL-ARCHITECTURE.md)** — Shell module architecture
- **[SHELL-MODULES.md](SHELL-MODULES.md)** — Module reference
- **[LUMINA-INTEGRATION.md](LUMINA-INTEGRATION.md)** — Desktop configuration (baremetal)
- **[ADMIN-PANEL.md](ADMIN-PANEL.md)** — Admin UI specification (baremetal)
- **[TESTING.md](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](https://codeberg.org/Clawdie/Clawdie-ISO/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