clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ISO builder, firstboot wizard, installer
12 commits 1 branch 3 tags 51 MiB
Find a file
Sam & Claude a7ea1e350c v0.9.0-rc2: Integrate feedback — recovery, POSIX, security, audio 
Addressed community feedback with FreeBSD-first approach:

✅ Recovery & Resilience:
  - clawdie-firstboot --resume (continue from checkpoint)
  - clawdie-firstboot --reset (start over)
  - Progress logging to /var/log/clawdie-firstboot.progress
  - All errors captured with line numbers + recovery instructions

✅ POSIX Compliance (FreeBSD-First):
  - All shell modules use POSIX sh (no bash-isms)
  - set -eu + trap ERR for reliable error handling
  - No Linux-specific tools (no systemd, apt, /dev/sda paths)
  - Maximum portability on FreeBSD

✅ API Key Security:
  - .env created with chmod 600 (user-only readable)
  - API keys never logged or echoed
  - Encrypted vault option planned for v1.0

✅ Audio (OSS Native):
  - FreeBSD OSS (not PulseAudio) — kernel-native
  - Audio card detection in admin panel (post-firstboot)
  - WiFi firmware detection + install guidance
  - Bluetooth support deferred to v1.0

✅ Post-Install Hardware:
  - Hardware detection submenu in admin panel
  - WiFi firmware suggestions
  - Audio troubleshooting guidance
  - Static IP via bsdinstall (not wizard)

✅ Upgrade Path:
  - Manual upgrade documented
  - clawdie-upgrade skill planned for v1.0
  - Admin panel upgrade button planned for v1.0

✅ v1.0 Roadmap:
  - New roadmap section in CLAWDIE-SHELL.md
  - Lists planned features: encryption, Bluetooth, network wizard, etc.

All changes maintain FreeBSD-native philosophy.
No Linux-isms welcome. OSS over PulseAudio.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-06-04 20:04:21 +02:00
firstboot feat: CI/CD pipeline, package lists, offline pkg-cache seeding 2026-06-04 20:04:21 +02:00
packages feat: CI/CD pipeline, package lists, offline pkg-cache seeding 2026-06-04 20:04:21 +02:00
runner docs(runner): add edk2-bhyve to build automation prerequisites 2026-06-04 20:04:21 +02:00
scripts feat(build): unblock ISO payload injection 2026-06-04 20:04:21 +02:00
skills/build-iso feat(skills): add build-iso skill v0.0.1 2026-06-04 20:04:21 +02:00
.gitignore Clawdie Shell specification v0.9.0-rc1 2026-06-04 20:04:21 +02:00
ADMIN-PANEL.md v0.9.0-rc2: Integrate feedback — recovery, POSIX, security, audio 2026-06-04 20:04:21 +02:00
build.cfg fix(build): use EU date format for user-facing ISO filename 2026-06-04 20:04:21 +02:00
build.sh feat(build): unblock ISO payload injection 2026-06-04 20:04:21 +02:00
CLAWDIE-ISO.md feat: initial clawdie-iso skeleton 2026-06-04 20:04:21 +02:00
CLAWDIE-SHELL.md v0.9.0-rc2: Integrate feedback — recovery, POSIX, security, audio 2026-06-04 20:04:21 +02:00
installerconfig feat: initial clawdie-iso skeleton 2026-06-04 20:04:21 +02:00
LUMINA-INTEGRATION.md Clawdie Shell specification v0.9.0-rc1 2026-06-04 20:04:21 +02:00
POUDRIERE-IMPLEMENTATION.md fix(poudriere): correct subnet, bridge, diagram and CI alignment 2026-06-04 20:04:21 +02:00
README.md Clawdie Shell specification v0.9.0-rc1 2026-06-04 20:04:21 +02:00
REFACTOR-SUMMARY.md v0.9.0-rc2: Integrate feedback — recovery, POSIX, security, audio 2026-06-04 20:04:21 +02:00
SHELL-ARCHITECTURE.md v0.9.0-rc2: Integrate feedback — recovery, POSIX, security, audio 2026-06-04 20:04:21 +02:00

README.md

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-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:

    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: 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

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

🔒 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-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 for full specification.

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