Sam & Claude
1bffa175c8
BREAKING CHANGE: Removes --target and --gpu-driver flags, unified ISO for all use cases ## Phase 0: GPU Fix + Unified ISO ### Core Changes **GPU Package Installation (FIXES CRITICAL GAP):** - Add clawdie_shell_nvidia_install() function to shell-nvidia.sh - NVIDIA drivers now installed after detection (previously only configured) - Works offline (USB packages) or online (pkg install) - Resolves issue where rc.conf was set but driver not installed **Unified ISO Architecture:** - Remove --target flag from build.sh (no more vps/baremetal branching) - Remove --gpu-driver flag from build.sh (runtime detection instead) - All packages included on every ISO (desktop + all GPU drivers) - Single image works on VPS, baremetal, and cloud **Runtime Detection:** - Add shell-desktop.sh for display detection at firstboot - VPS/cloud: no display → lightdm disabled (headless) - Baremetal: display detected → lightdm enabled (Lumina desktop) - GPU detection always runs, installs correct driver version **Sudo Unification:** - Replace all doas references with sudo across entire codebase - Update AGENTS.md with system configuration guidelines - Update all documentation (BUILD.md, README.md, REQUIREMENTS.md, etc.) - Admin panel now uses sudo for privileged operations ### Files Modified **Core System:** - build.sh: Remove target/gpu-driver logic, unified package selection - firstboot/firstboot.sh: Add desktop detection module - firstboot/shell-nvidia.sh: Add package installation function (+33 lines) **New Files:** - firstboot/shell-desktop.sh: Display detection and desktop enablement - packages/pkg-list-nvidia-all.txt: All three NVIDIA driver versions (390/470/590) - .opencode/plans/phase0-gpu-fix-unified-iso.md: Implementation plan **Documentation:** - PLAN-UNIFY.md: Update Step 3 for unified approach - REQUIREMENTS.md: Simplify (no target choice), update for sudo - BUILD.md: Update for unified ISO, sudo commands - README.md: Update installation instructions - AGENTS.md: Add system configuration section (sudo standardization) - ADMIN-PANEL.md: Update privileged operations to use sudo - CLAWDIE-SHELL.md: Update example commands to sudo - CLAWDIE-ISO-REFACTORED.md: Update access paths to sudo - REFACTOR-SUMMARY.md: Update permissions section to sudo ### Benefits **Simplicity:** - One build command: ./build.sh (no flags needed) - One ISO to test and maintain - No wrong choices for users - No documentation explaining target differences **Flexibility:** - VPS can use GUI via VNC (wayvnc always available) - Baremetal can run headless (disable lightdm) - Repurpose hardware without reinstall - All GPU drivers available for any hardware **Technical:** - Fixes critical GPU driver installation gap - Runtime detection replaces build-time decisions - Disk overhead: ~650MB (1-2% of 50GB - acceptable) - No runtime overhead on VPS (services disabled by detection) ### Testing Required - [ ] Build unified ISO: ./build.sh - [ ] Test on VPS (no display): lightdm disabled, packages installed - [ ] Test on baremetal (display): lightdm enabled, Lumina boots - [ ] Test on NVIDIA hardware: driver installed and loaded - [ ] Test sudo commands work without password prompts - [ ] Verify all doas references removed
199 lines
6 KiB
Markdown
199 lines
6 KiB
Markdown
# 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`
|
||
|
||
---
|
||
|
||
## 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-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](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
|