clawdie-iso/CLAWDIE-SHELL.md

Clawdie Shell — FreeBSD-Native Agent Workstation

Status: Architecture specification — 23.mar.2026 Version: v0.9.0-rc1 Philosophy: Standing on the shoulders of FreeBSD, Lumina, and PC-BSD

---

What Is Clawdie Shell?

Clawdie Shell is an opinionated FreeBSD-based workstation designed to deploy AI agent systems. It combines:

• FreeBSD 15.0 as the OS (ZFS, jails, rc.d, pkg)
• Lumina Desktop as the UI (FreeBSD-native, from PC-BSD heritage)
• Shell scripting as the deployment layer (POSIX-portable, no VM overhead)
• Bastille jails for process isolation and multi-service architecture

Not a generic Linux distro on FreeBSD. Built for FreeBSD, by FreeBSD philosophy.

---

Standing on Giants' Shoulders

Clawdie Shell doesn't reinvent. It inherits proven tools:

Giant	Contribution	How We Use It
FreeBSD	ZFS, jails, rc.d, security model, stability	Core OS, container isolation, service management
PC-BSD	Lumina desktop, installer patterns, user-first design	Desktop environment, installation UX
POSIX shell	Portability, simplicity, standardization	Deployment modules (sh-based, no external VMs)
bsddialog	Native FreeBSD UI toolkit	Installer wizard, admin panel menus
Bastille	Lightweight jail orchestration	Multi-service architecture (worker, db, cms jails)

---

Why "Shell"?

The name captures two meanings:

1. Implementation: All setup and admin tools are shell-based (sh scripts), modular, and portable
2. Interface: Provides a complete user shell/environment for agent deployment — not just a thin installer

Philosophy: Shell scripting done right is faster, more debuggable, and more FreeBSD-native than importing heavy frameworks.

---

One Reboot, One Wizard

Goal: USB → bsdinstall → 3-tier wizard → reboot → fully configured agent workstation

USB boot
  └─ bsdinstall (standard FreeBSD installer)
       ├─ Disk partitioning (ZFS)
       ├─ Root password, clawdie user account
       └─ POST-INSTALL (installerconfig):
            ├─ Copy shell modules + clawdie-admin to HDD
            ├─ Install rc.d clawdie-firstboot service
            └─ Reboot

FIRST BOOT FROM HDD (reboot 1)
  └─ rc.firstboot (clawdie-firstboot service)
       ├─ [bsddialog] Welcome screen
       ├─ [TIER 1] Identity (name, domain, timezone) — 3 screens
       ├─ [TIER 2] Optional (LLM provider, Telegram) — 2 screens
       ├─ [SUMMARY] Review + confirm
       └─ [SETUP] Non-interactive:
            ├─ Source clawdie-shell-*.sh modules
            ├─ Configure packages, GPU, system
            ├─ Generate .env
            ├─ Extract Clawdie-AI, npm install
            ├─ Provision jails (worker, db, cms)
            ├─ Start services
            └─ Boot into Lumina desktop

Running system
  └─ Lumina + Clawdie service ready
       ├─ Taskbar with system tray
       ├─ Right-click → "Clawdie Admin" (bsddialog panel)
       └─ User can interact with agent immediately

---

Key Features

1. Shell-First Architecture

Instead of a monolithic wizard:

firstboot.sh (orchestrator)
  ├─ sources clawdie-shell-env.sh     (identity, .env generation)
  ├─ sources clawdie-shell-pkg.sh     (repo config, package setup)
  ├─ sources clawdie-shell-gpu.sh     (GPU detection)
  ├─ sources clawdie-shell-system.sh  (rc.conf, timezone, dbus)
  └─ sources clawdie-shell-clawdie.sh (tarball extract, npm install)

Benefits:

• Testable: each function independent
• Reusable: source on any FreeBSD host, outside installer context
• Debuggable: run individual functions to diagnose issues
• Fast: no Node.js bootstrap overhead

2. Lumina Desktop (FreeBSD-Native)

• Lightweight (~150 MB RAM footprint)
• Designed for BSD (from PC-BSD)
• Openbox window manager (simple, stable)
• No Linux assumptions (no systemd, udev, etc.)

3. Admin Panel (bsddialog UI)

clawdie-admin: Right-click Lumina taskbar → system administration

┌─ Clawdie Admin Panel ─────────────┐
│ System Health                     │
│ Jails (worker, db, cms)           │
│ ZFS Snapshots (inspired by        │
│   PC-BSD Life-Preserver)          │
│ Logs (service, jails, system)     │
│ Configuration (name, timezone)    │
└───────────────────────────────────┘

No external GUI toolkit—pure bsddialog (FreeBSD standard).

4. ZFS Awareness

• Snapshot creation/restore from admin panel
• Auto-backup scheduling (optional)
• Pool health monitoring
• Inspired by PC-BSD's Life-Preserver design

---

Default Configuration

Item	Value	Rationale
FreeBSD version	15.0-RELEASE	Stable, long-term support
Desktop	Lumina	FreeBSD-native, lightweight
Package branch	latest	Better GPU driver support
Jails	worker, db, cms, mgmt	Clawdie architecture
Init system	rc.d (FreeBSD standard)	Simple, reliable
Package manager	pkg	FreeBSD standard
Shell	sh (POSIX)	Portable, no bash-isms

---

Repo Structure

clawdie-shell/
├── README.md                        ← Overview
├── CLAWDIE-SHELL.md                 ← This file (specification)
├── SHELL-ARCHITECTURE.md            ← Shell modules deep dive
├── GETTING-STARTED.md               ← User installation guide
├── LUMINA-INTEGRATION.md            ← Desktop configuration
├── ADMIN-PANEL.md                   ← Admin UI specification
├── REFACTOR-SUMMARY.md              ← Why we changed from multi-DE
│
├── build.sh                         ← Build FreeBSD memstick image
├── build.cfg                        ← Configuration (versions, sizes)
├── installerconfig                  ← bsdinstall post-install hook
│
├── firstboot/
│   ├── firstboot.sh                 ← 3-tier wizard orchestrator
│   ├── clawdie-shell-env.sh         ← Identity + .env generation
│   ├── clawdie-shell-pkg.sh         ← Package repo setup
│   ├── clawdie-shell-gpu.sh         ← GPU detection
│   ├── clawdie-shell-system.sh      ← System configuration
│   ├── clawdie-shell-clawdie.sh     ← Clawdie-AI setup
│   ├── gpu-detect.sh                ← PCI ID → kld mapping
│   ├── clawdie-admin.sh             ← Admin panel UI
│   └── rc.d/
│       └── clawdie-firstboot        ← rc.d service (runs once)
│
├── lumina-config/
│   ├── luminarc                     ← Lumina main config
│   ├── panel.conf                   ← Panel layout
│   └── openbox-rc.xml               ← Window manager config
│
├── packages/
│   ├── pkg-list-host.txt            ← Host baseline
│   ├── pkg-list-lumina.txt          ← Lumina desktop
│   ├── pkg-list-desktop-base.txt    ← X11 base
│   ├── pkg-list-jails.txt           ← Jail packages
│   └── pkg-list-nvidia.txt          ← GPU drivers
│
├── CLAWDIE-ISO.md                   ← Archive: old multi-DE plan
└── CLAWDIE-ISO-REFACTORED.md        ← Archive: intermediate version

---

Package Manifest

Host Baseline (clawdie-shell-ready)

Essential packages for Clawdie-AI deployment:

• node24, npm, bastille, git, tmux, bsddialog
• postgresql17-client, python311, uv, ripgrep, fd
• desktop-installer (for gpu-detect.sh)

Lumina Desktop

Lightweight FreeBSD-native DE:

• lumina-core, lumina-themes, lumina-filemanager
• openbox (window manager), lightdm (login manager)
• dbus, hal (device management)

Jails Support

Packages bundled for offline jail provisioning:

• worker: node24, npm, cage (for UI tasks)
• db: postgresql17-server, pgvector
• cms: nginx, node24, npm
• mgmt: victoria-metrics, grafana10 (optional)

Total ISO size: 2–2.5 GB (vs 2.5–3 GB with multi-DE)

---

Installation Flow

Option A: Standard (Guided Wizard)

1. Boot Clawdie Shell USB
2. Run bsdinstall (disk layout, user setup)
3. On first boot: 3-tier wizard (identity, LLM, Telegram)
4. Non-interactive setup (packages, jails, services)
5. Reboot → Lumina desktop + Clawdie ready

Option B: Unattended (Pre-Config)

Create clawdie.conf on USB before booting:

ASSISTANT_NAME=Clawdie
AGENT_DOMAIN=clawdie.local
TZ=Europe/Ljubljana
LLM_PROVIDER=anthropic

Installer reads config, skips wizard screens for filled fields.

---

Recovery & Resilience

Resume on Failure

If firstboot wizard encounters an error:

# Check progress
cat /var/log/clawdie-firstboot.progress

# Resume from last checkpoint
clawdie-firstboot --resume

# Start completely over
clawdie-firstboot --reset

Each tier (identity, LLM, Telegram, setup) logs completion:

[TIER-1] COMPLETE
[TIER-2] COMPLETE
[SETUP] pkg COMPLETE
[SETUP] gpu COMPLETE
[SETUP] system COMPLETE
[SETUP] env COMPLETE
[SETUP] clawdie COMPLETE

Design principle: No wizard state is lost. Resume from where it failed.

Error Handling

All shell modules use POSIX-compliant error handling:

set -eu  # Exit on error, undefined vars (POSIX-safe, no bash-isms)
trap 'echo "ERROR at line $LINENO in $0" >&2; exit 1' ERR

Each error is logged to /var/log/clawdie-firstboot.log with:

• Line number and function name
• State at time of failure
• Recovery instructions

---

Security Considerations

API Key Storage

LLM provider keys are collected during firstboot:

• Storage: .env file with permissions 600 (user-only)
• Logging: Keys never appear in logs or console output
• Validation: Keys tested before saving (optional prompt if invalid)
• Post-install: Keys can be updated via admin panel (manually, in v1.0)

.env Permissions

Automatically set during setup:

chmod 600 /home/clawdie/clawdie-ai/.env  # Only clawdie user can read
chown clawdie:clawdie /home/clawdie/clawdie-ai/.env

Future: Encrypted Storage (v1.0)

Consider encrypted .env vault using FreeBSD geli:

# v1.0 feature (not v0.9.0)
# Encrypt .env with user passphrase
# Mount on agent startup

---

Audio Configuration

Default: FreeBSD OSS (Open Sound System — native, no Linux deps)

Clawdie Shell includes OSS support for:

• Agent audio output (TTS responses)
• Operator audio input (voice commands, future)
• System notifications (optional)

Why OSS, Not PulseAudio?

• FreeBSD-native: Built into kernel, no external daemon
• Minimal: No middleware complexity
• Stable: Decades of use on FreeBSD
• Operator-friendly: Works out-of-box for human interaction

Hardware Detection (Post-Install)

Admin panel detects sound card on first boot:

# In clawdie-admin post-firstboot
dmesg | grep -i audio
cat /dev/sndstat

If no audio device found:

• Suggest pkg install snd-hda-generic for Intel/AMD
• Suggest pkg install snd-usb-audio for USB headsets
• Document for operator

Sound Card Package List

Added to pkg-list-host.txt:

• alsa-lib (compatibility layer, optional)
• devel/libsndfile (audio file support)
• snd-hda-generic (Intel/AMD chipset support, auto-detected)

---

Admin Panel Access

From Desktop

Right-click Lumina taskbar system tray:

[Network] [Volume] [Clock] [Clawdie ✓]
                           └─ Right-click → "Clawdie Admin"

From Terminal

$ clawdie-admin
# Opens interactive bsddialog menu

From File Manager

Double-click ~/.local/share/applications/clawdie-admin.desktop

---

Philosophy: "Giants' Shoulders"

Every choice in Clawdie Shell respects prior art:

FreeBSD: We don't fight the OS. We use its idioms (rc.d, pkg, jails, ZFS).

PC-BSD: Lumina wasn't an accident. PC-BSD chose it for good reason. We inherit that wisdom.

Warden & Life-Preserver: Shell-based tools that worked. We follow that pattern.

POSIX shell: Portable, debuggable, no external VMs. Proven for 40+ years.

bsddialog: Native FreeBSD UI. No GTK/Qt bloat.

---

Version History

• v0.9.0-rc1 (23.mar.2026) — Initial "Shell" branding, Lumina default, admin panel
• v0.9.0 (planned) — Stable release after hardware testing
• v1.0.0 (planned) — Multi-arch support (amd64, arm64)

---

Known Limitations

1. Single desktop — Lumina only (can install XFCE/KDE post-install)
2. X11 only — Wayland not supported (Lumina uses X11)
3. Single monitor optimized — Multi-monitor support basic
4. No cloud init — Designed for manual/interactive deployment
5. DHCP assumed — Static IP configuration via bsdinstall (pre-install)
6. WiFi firmware post-install — Detected and suggested after first boot

---

Out of Scope

Bluetooth: Deliberately excluded.

Rationale:

• FreeBSD Bluetooth stack is less mature than Linux; tight integration adds complexity
• Agent workstations are typically in fixed locations (office/rack) with wired Ethernet
• Keyboard/mouse via USB are standard; wireless peripherals are less critical
• Focus: reliable, headless-capable deployment over feature breadth
• Post-install: Users requiring Bluetooth can manually configure via hcsecd and rfcomm if needed

Decision: No Bluetooth in Clawdie Shell v0.9.0, v1.0, or future versions. FreeBSD-first focus trumps feature parity.

---

Next Steps (Implementation)

1. ✅ Design (this spec)
2. Create shell modules (clawdie-shell-*.sh)
3. Rewrite firstboot.sh as 3-tier wizard
4. Implement clawdie-admin (bsddialog panel)
5. Configure Lumina defaults
6. Test on 3+ hardware configs
7. Tag v0.9.0-rc1, prepare release ISO

---

Upgrade & Maintenance

Manual Upgrade Path (v0.9.0)

Users can upgrade Clawdie-AI manually after initial deployment:

# SSH into agent workstation
ssh clawdie@clawdie.local

# Update source code
cd ~/clawdie-ai
git fetch origin
git checkout v0.9.1  # or latest tag

# Install dependencies + redeploy
npm install
npm run install-all

# Restart service
doas service clawdie restart

# Verify
service clawdie status

Post-Install Hardware Tuning

WiFi Firmware Detection (post-firstboot):

Admin panel alerts operator:

⚠️ WiFi detected: Intel 8260
→ Suggested: pkg install iwm-firmware-8260
→ Or: doas pkg install iwm-firmware

Audio Card Detection:

# If no audio:
cat /dev/sndstat
dmesg | grep -i audio

# Common fixes:
pkg install snd-hda-generic    # Intel/AMD
pkg install snd-usb-audio      # USB headsets

---

Roadmap: v1.0 Features

Feature	Scope	Status
clawdie-upgrade	Admin panel upgrade button	Planned
Encrypted .env	geli vault for sensitive vars	Planned
Multi-monitor	Better panel layout on multiple displays	Planned
WiFi firmware helper	Auto-detect and suggest WiFi fw	Planned
Network wizard	Static IP, DNS, proxy config	Planned
System backup	Automated ZFS snapshot scheduling	Planned

---

Contributing

Clawdie Shell welcomes improvements:

• Bug reports: GitHub issues (installer, admin panel, hardware support)
• Feature requests: Discuss in issues before implementing
• Custom desktops: Users can pkg install xfce post-install
• Architecture changes: Submit RFC with rationale

Philosophy: Keep Clawdie Shell focused (one DE, one purpose). Don't reinvent—inherit.

---

License

Clawdie Shell respects the licenses of projects it builds upon:

• FreeBSD (BSD 2-Clause)
• Lumina Desktop (BSD 3-Clause)
• Bastille (BSD 3-Clause)
• PC-BSD/TrueOS heritage (public domain / BSD)

Clawdie Shell itself: [Your choice — likely same as clawdie-ai]

---

Contact & Community

• Project: https://clawdie.si/
• Repository: https://codeberg.org/Clawdie/clawdie-shell
• Issues: Codeberg issues
• Discussion: Codeberg discussions

---

Appendix: Why Shell?

vs. Python

• Python startup: 100–200 ms
• Shell startup: 5 ms
• Python packages: external deps, version conflicts
• Shell: POSIX standard, no deps

For a first-boot installer that runs once, shell is 20× faster.

vs. Node.js

• Node.js startup: 300–500 ms
• Node.js footprint: needs npm, node_modules
• Shell: single file, sourced

For modular, reusable functions, shell is cleaner.

vs. C

• C requires compilation, pkg maintainers
• Shell: edit, test, run
• Deployment: copy files, no build step needed

For maintainability, shell wins.

---

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