clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: announce Tailscale mandatory, --target flag, glasspane, repo unification (Sam & Claude)

Browse source 
- README: rewrite for unified iso repo, two targets, mandatory Tailscale pre-req
- BUILD: add Step 0 (auth key), --target flag, --insecure-no-tailscale, first boot Tailscale screen 1
- AGENTS: note clawdie-shell archived, clawdie-iso is canonical, point to PLAN-UNIFY.md
This commit is contained in:
Sam & Claude 2026-04-06 03:44:02 +00:00 • committed by 123kupola
parent a421084c37
commit 5c36f239cd
3 changed files with 152 additions and 95 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
AGENTS.md
View file

@ -1,5 +1,14 @@
# Clawdie ISO Agent Guidelines
## Repo Status
`clawdie-iso` is the **single canonical repo** for all Clawdie installation targets.
The `clawdie-shell` repo is being **archived** (read-only). Do not make new commits there.
All work goes into `clawdie-iso`. See `PLAN-UNIFY.md` for the active implementation plan.
---
## Attribution in Commit History
Use attribution in commit messages, not in code comments.

46
BUILD.md
View file

@ -1,6 +1,7 @@
# Clawdie Shell (bundles Clawdie-AI v1.0.2) — ISO Builder
# Clawdie ISO (bundles Clawdie-AI v1.0.2) — ISO Builder
Building a bootable Clawdie Shell installer ISO with offline package support.
Building a bootable Clawdie ISO installer with offline package support.
Supports two targets: `--target baremetal` (Lumina desktop) and `--target vps` (headless).
## Prerequisites
@ -9,6 +10,16 @@ Building a bootable Clawdie Shell installer ISO with offline package support.
pkg install curl
```
**Tailscale auth key (mandatory):**
Tailscale is required — it is the security perimeter. Generate a key before building:
1. Sign up free at https://tailscale.com (free up to 100 devices)
2. Admin console → Settings → Keys → Generate auth key (check "Reusable" for multi-deploy)
3. Export before building: `export TAILSCALE_AUTHKEY="tskey-auth-..."`
Without `TAILSCALE_AUTHKEY` the build will fail. Use `--insecure-no-tailscale` only for
air-gapped environments — you are responsible for securing SSH access in that case.
**USB Key Requirements:**
| USB Size | Recommended | Spare Space | Notes |
|----------|-------------|-------------|-------|
@ -20,6 +31,11 @@ pkg install curl
## Quick Start
### Step 0: Set Tailscale auth key
```bash
export TAILSCALE_AUTHKEY="tskey-auth-..."
```
### Step 1: Fetch packages (no root needed)
```bash
./build.sh --fetch-only
@ -33,7 +49,11 @@ Takes ~30 min on fast connection. Can be interrupted/resumed.
### Step 2: Build ISO (requires root)
```bash
sudo ./build.sh --skip-fetch
# Baremetal target (Lumina desktop, default):
doas ./build.sh --skip-fetch --target baremetal
# VPS/cloud target (headless, cage + wayvnc only):
doas ./build.sh --skip-fetch --target vps
```
Creates 50GB image with:
@ -73,13 +93,23 @@ DEFAULT_PKG_BRANCH="latest" # Package branch (latest or quarterly)
# Build from cached packages (no download)
./build.sh --skip-fetch
# Build targets
./build.sh --target baremetal # Lumina desktop (default)
./build.sh --target vps # Headless + cage/wayvnc
# Override Clawdie version
./build.sh --clawdie-version 1.0.2
# Headscale (self-hosted Tailscale control server)
./build.sh --tailscale-login-server https://your-headscale-host
# Air-gapped environments only (no Tailscale — you own the security)
./build.sh --insecure-no-tailscale
# Combine flags
./build.sh --fetch-only
# ... later, on another system ...
./build.sh --skip-fetch --clawdie-version 1.0.2
# ... later ...
./build.sh --skip-fetch --target vps --clawdie-version 1.0.2
```
## Build Process (7 steps)
@ -105,12 +135,14 @@ When you boot a machine from the USB:
1. **bsdinstall** runs FreeBSD installer (standard workflow)
2. **installerconfig hook** (post-install) injects firstboot payload to HDD
3. **clawdie-firstboot service** runs on first HDD boot
4. **firstboot.sh** wizard guides user through:
4. **firstboot.sh** wizard guides user through (baremetal):
- **Screen 1: Tailscale auth key** (mandatory — system is not accessible without it)
- Identity setup (name, domain, timezone)
- Package repo config (online + offline USB)
- GPU detection + driver selection
- System config (hostname, services)
- System config (hostname, services, PF firewall)
- Clawdie-AI deployment + jail setup
5. VPS/cloud: no wizard — all config pre-baked in build.cfg at build time
See `firstboot/MODULE-MANIFEST.md` for wizard architecture.

192
README.md
View file

@ -1,27 +1,46 @@
# Clawdie Shell
# Clawdie ISO
**Unified installer and human operator interface for Clawdie-AI on FreeBSD**
**Unified installer for Clawdie-AI on FreeBSD — baremetal and VPS**
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)
A single-step deployment platform with two targets:
- `--target baremetal` — Lumina desktop + Wayland + full operator UI
- `--target vps` — headless + Wayland (cage) for browser automation
**Standing on the shoulders of giants:** We don't reinvent. We inherit wisdom from FreeBSD, PC-BSD's Lumina, and proven shell patterns.
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.
---
## What Is Clawdie Shell?
## Pre-Install Requirements
Boot a USB, answer a 3-screen wizard, and you have a fully configured Clawdie-AI workstation running on FreeBSD with:
Before building or booting:
- ✅ Lumina desktop (ready to use)
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
- ✅ All offline (no internet required during install)
**One reboot. That's it.**
@ -32,56 +51,58 @@ Boot a USB, answer a 3-screen wizard, and you have a fully configured Clawdie-AI
### Build the USB Image
```bash
# Requirements: FreeBSD 15.0+, pkg, curl, 30 GB free disk space
# 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 for mdconfig/mount)
doas ./build.sh
# Assemble ISO (requires root)
# Default target is baremetal. For VPS:
doas ./build.sh --target vps
# or:
doas ./build.sh --target baremetal
# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img (~50 GB, configurable in build.cfg)
# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img (~50 GB)
```
### Install on Hardware
### Install on Hardware (baremetal)
1. **Write to USB:**
```bash
doas dd if=tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img of=/dev/da0 bs=1M
# (replace da0 with your USB device)
doas dd if=tmp/output/clawdie-iso-baremetal-DD.mmm.YYYY.img of=/dev/da0 bs=1M
```
2. **Boot from USB** on target machine (BIOS/EFI)
2. **Boot from USB**, run bsdinstall (choose disk, root password, create `clawdie` user)
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)
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)
5. **Lumina desktop boots**
- Login as `clawdie` user
- Agent running in background
- Admin panel: right-click taskbar → "Clawdie Admin"
4. **Lumina desktop boots** (baremetal) or agent starts (VPS)
- Glasspane: `ssh clawdie@<tailscale-ip>` → tmux
- Glasspane visual: connect wayvnc on `<tailscale-ip>:5900`
---
## 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
- **[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
---
@ -91,6 +112,7 @@ doas ./build.sh
|-------|--------------|
| **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 |
@ -99,31 +121,41 @@ doas ./build.sh
## Features
### 🖥️ Lumina Desktop
- Lightweight (~150 MB RAM)
- Designed for FreeBSD (from PC-BSD)
- Openbox window manager, stable, simple
### Glasspane (Remote Operator Access)
### 🛠️ Admin Panel
Right-click Lumina taskbar → "Clawdie Admin":
- System Health (CPU, RAM, ZFS pool)
- Jails (start/stop, console)
- ZFS Snapshots (create, restore)
- Logs, Configuration
Both targets ship with the full glasspane stack:
### 📦 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
```
Operator → Tailscale → SSH → tmux (watch agent terminal panes)
Operator → Tailscale → wayvnc:5900 → cage → Chromium (watch browser automation)
```
### 🧰 Local Git (Forgejo-ready)
- Plain git jail by default
- Optional Forgejo web UI (runs in `{agent}-git` on port `3000`, internal only)
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
### 🔒 Offline-First
- All packages bundled on USB
- Reproducible deploys
- Falls back to online if connected
@ -136,50 +168,34 @@ Modular, reusable, testable:
- **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.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
- **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)
- X11 only (no Wayland)
- Interactive deployment (no cloud-init)
- 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:** Keep focused (one DE, one purpose). Inherit, don't reinvent.
- **Philosophy:** Secure by default, opinionated where it matters, inherit don't reinvent.
---
## Building
```bash
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](CLAWDIE-SHELL.md) for full specification.
---
**Last updated:** 23.mar.2026
**Standing on:** FreeBSD, Lumina, PC-BSD wisdom
**Last updated:** 06.apr.2026
**Standing on:** FreeBSD, Lumina, PC-BSD wisdom, Tailscale