184 lines
4.8 KiB
Markdown
184 lines
4.8 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# Requirements: FreeBSD 15.0+, pkg, curl, 30 GB free disk space
|
||
|
||
git clone https://codeberg.org/Clawdie/clawdie-shell.git
|
||
cd clawdie-shell
|
||
|
||
# Fetch FreeBSD memstick + all packages (non-root)
|
||
./build.sh --fetch-only
|
||
|
||
# Assemble ISO (requires root for mdconfig/mount)
|
||
doas ./build.sh
|
||
|
||
# Output: clawdie-shell-YYYYMMDD.img (~2-2.5 GB)
|
||
```
|
||
|
||
### Install on Hardware
|
||
|
||
1. **Write to USB:**
|
||
```bash
|
||
doas dd if=clawdie-shell-YYYYMMDD.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 3 questions: assistant name, domain, timezone
|
||
- Optional: enable Forgejo web git UI (adds disk usage)
|
||
- Optional: LLM provider, Telegram bot
|
||
- 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](CLAWDIE-SHELL.md)** — Specification (overview, features, design)
|
||
- **[SHELL-ARCHITECTURE.md](SHELL-ARCHITECTURE.md)** — Technical deep-dive (shell modules, patterns)
|
||
- **[LUMINA-INTEGRATION.md](LUMINA-INTEGRATION.md)** — Desktop configuration
|
||
- **[ADMIN-PANEL.md](ADMIN-PANEL.md)** — Admin UI specification
|
||
- **[REFACTOR-SUMMARY.md](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](https://codeberg.org/Clawdie/clawdie-shell/issues)
|
||
- **Philosophy:** Keep focused (one DE, one purpose). Inherit, don't reinvent.
|
||
|
||
---
|
||
|
||
## Building
|
||
|
||
```bash
|
||
git clone https://codeberg.org/Clawdie/clawdie-shell.git
|
||
cd clawdie-shell
|
||
|
||
# Fetch packages (non-root)
|
||
./build.sh --fetch-only
|
||
|
||
# Build ISO (requires root)
|
||
doas ./build.sh
|
||
|
||
# Output: clawdie-shell-YYYYMMDD.img
|
||
```
|
||
|
||
See [CLAWDIE-SHELL.md](CLAWDIE-SHELL.md) for full specification.
|
||
|
||
---
|
||
|
||
**Last updated:** 23.mar.2026
|
||
**Standing on:** FreeBSD, Lumina, PC-BSD wisdom
|