Clawdie Shell

Unified installer and human operator interface for Clawdie-AI on FreeBSD

A single-step deployment platform that combines:

• FreeBSD 15.0 (ZFS, jails, rc.d, pkg)
• Lumina Desktop (lightweight, FreeBSD-native, from PC-BSD heritage)
• Shell modules (modular, portable, POSIX-compliant)
• Admin panel (bsddialog UI for jails, snapshots, system health)

Standing on the shoulders of giants: We don't reinvent. We inherit wisdom from FreeBSD, PC-BSD's Lumina, and proven shell patterns.

---

What Is Clawdie Shell?

Boot a USB, answer a 3-screen wizard, and you have a fully configured Clawdie-AI workstation running on FreeBSD with:

• ✅ Lumina desktop (ready to use)
• ✅ Bastille jails (worker, db, cms) provisioned
• ✅ PostgreSQL + pgvector seeded
• ✅ Clawdie-AI agent running
• ✅ Admin panel accessible from taskbar
• ✅ All offline (no internet required during install)

One reboot. That's it.

---

Quick Start

Build the USB Image

# Requirements: FreeBSD 15.0+, pkg, curl, 30 GB free disk space

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

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

# Assemble ISO (requires root for mdconfig/mount)
doas ./build.sh

# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img (~50 GB, configurable in build.cfg)

Install on Hardware

1. Write to USB:

   doas dd if=tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img of=/dev/da0 bs=1M
   # (replace da0 with your USB device)
   

2. Boot from USB on target machine (BIOS/EFI)

3. Run bsdinstall (standard FreeBSD installer)

   • Choose disk, partitioning, root password
   • Create clawdie user

4. First boot from HDD (reboot 1)

   • rc.firstboot wizard appears
   • Answer: assistant name, public domain, timezone
   • Optional: local LLM runtime (Ollama or llama-cpp)
   • Optional: SSH public key (for later Ansible/jail SSH baselines)
   • Optional: enable Forgejo web git UI (adds disk usage)
   • Setup runs automatically (5–10 min)

5. Lumina desktop boots

   • Login as clawdie user
   • Agent running in background
   • Admin panel: right-click taskbar → "Clawdie Admin"

---

Documentation

• CLAWDIE-SHELL.md — Specification (overview, features, design)
• SHELL-ARCHITECTURE.md — Technical deep-dive (shell modules, patterns)
• LUMINA-INTEGRATION.md — Desktop configuration
• ADMIN-PANEL.md — Admin UI specification
• REFACTOR-SUMMARY.md — Why Lumina-only, not multi-DE

---

Philosophy: Standing on Giants' Shoulders

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

---

Features

🖥️ Lumina Desktop

• Lightweight (~150 MB RAM)
• Designed for FreeBSD (from PC-BSD)
• Openbox window manager, stable, simple

🛠️ Admin Panel

Right-click Lumina taskbar → "Clawdie Admin":

• System Health (CPU, RAM, ZFS pool)
• Jails (start/stop, console)
• ZFS Snapshots (create, restore)
• Logs, Configuration

📦 Shell Modules

Modular, reusable, testable:

• clawdie-shell-env.sh — Identity + secrets
• clawdie-shell-pkg.sh — Repositories
• clawdie-shell-gpu.sh — GPU detection
• clawdie-shell-system.sh — System config
• clawdie-shell-clawdie.sh — AI setup + jails

🧰 Local Git (Forgejo-ready)

• Plain git jail by default
• Optional Forgejo web UI (runs in {agent}-git on port 3000, internal only)

🔒 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

---

Version History

• v0.9.0-rc1 (23.mar.2026) — Initial "Shell" branding, Lumina, modular architecture
• v0.9.0 (planned) — Stable release
• v1.0.0 (planned) — Multi-arch support

---

Known Limitations

• Single desktop (Lumina only)
• X11 only (no Wayland)
• Interactive deployment (no cloud-init)

---

Contributing

• Issues: Codeberg Issues
• Philosophy: Keep focused (one DE, one purpose). Inherit, don't reinvent.

---

Building

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

# Fetch packages (non-root)
./build.sh --fetch-only

# Build ISO (requires root)
doas ./build.sh

# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img

See CLAWDIE-SHELL.md for full specification.

---

Last updated: 23.mar.2026 Standing on: FreeBSD, Lumina, PC-BSD wisdom