Clawdie ISO

XFCE FreeBSD operator USB image for Clawdie-AI.

On the xfce-operator-usb branch, the active direction is a persistent XFCE operator USB:

• bootable USB image
• XFCE desktop
• browser available immediately
• minimal pi harness available immediately
• Tailscale available immediately
• no required Clawdie-AI services running on the USB by default

Current validation target: bootable dev image with BUILD_CHANNEL=dev and bundled Clawdie-AI from main. Public release images should use BUILD_CHANNEL=release and a pinned Clawdie-AI tag.

---

What You Get

Boot a USB and land in an operator environment:

• FreeBSD 15.0 base system
• XFCE desktop via LightDM autologin
• pre-LightDM live GPU detection for Intel, AMD/ATI, VMware, and conservative NVIDIA fallback
• Chromium browser on the live image
• Tailscale on the live image
• Bundled npm globals on the live image, including pi
• Offline package repository bundled on the USB image
• Clawdie-AI tarball with offline node_modules
• Static bootstrap page launched from the desktop
• desktop power actions allowed for wheel users, including clawdie

Provider keys, Telegram, browser sign-in, and disk deployment are intentionally deferred on this branch.

---

Pre-Install Requirements

Build host:

• FreeBSD 15.0+
• pkg, curl, Node/npm, sudo
• root or sudo for image assembly (mdconfig, mount, bootcode)
• 150 GB free build space recommended
• 32 GB USB key minimum for the default 28 GB image

Optional but recommended:

• Tailscale account and auth key (tskey-auth-...)

Tailscale is recommended, not mandatory. If no auth key is supplied, the ISO build continues with a warning and the live USB still boots normally.

---

Quick Start: Build Image

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

# Full build: fetch FreeBSD, packages, Clawdie-AI, then assemble image.
sudo ./build.sh

Useful alternatives:

# Fetch/cache only. Does not assemble an image.
./build.sh --fetch-only

# Reuse cached packages and image inputs.
# Safe for pinned tags/commits. For moving refs, build.sh caches by resolved commit.
sudo ./build.sh --skip-fetch

# Fetch packages but reuse the cached FreeBSD memstick image.
sudo ./build.sh --skip-memstick-fetch

# Dev/test image: set live user clawdie password to quindecim.
sudo ./build.sh --live-default-password

# Validation build from current Clawdie-AI main.
sudo ./build.sh --clawdie-ref main

# Release build from a pinned Clawdie-AI tag.
BUILD_CHANNEL=release sudo ./build.sh --clawdie-version 0.10.0

The build prints provenance similar to:

ISO     : 0.1.0-dev
FreeBSD : 15.0-RELEASE amd64
Clawdie : main
Clawdie commit: <sha>

It also writes build-manifest.json into the image and onto the installed system under /usr/local/share/clawdie-iso/.

Why quindecim

Artifact names use a short Latin codename for the FreeBSD major line they were built on. For FreeBSD 15, that codename is quindecim, so:

clawdie-xfce-quindecim-usb-DD.MM.YY.img

means:

• clawdie — project name
• xfce — desktop/session target
• quindecim — Latin for 15, matching the FreeBSD 15 build line
• usb — operator USB image
• DD.MM.YY — build date

Small reference for the current naming convention:

0  = nulla / nihil / zero
1  = unus
2  = duo
3  = tres
4  = quattuor
5  = quinque
6  = sex
7  = septem
8  = octo
9  = novem
10 = decem
11 = undecim
12 = duodecim
13 = tredecim
14 = quattuordecim
15 = quindecim
16 = sedecim
17 = septendecim
18 = duodeviginti
19 = undeviginti
20 = viginti
21 = viginti unus
22 = viginti duo
23 = viginti tres
24 = viginti quattuor
25 = viginti quinque
26 = viginti sex

Notes:

• For 0, Classical Latin did not have one universal everyday numeral word equivalent to modern zero; nulla and nihil are both common “none/nothing” stand-ins, while zero is later Latin.
• For 21+, Latin number phrasing has multiple acceptable styles. The forms above are intentionally simple and readable for image naming.

---

Write to USB

Published artifacts are compressed as .img.gz. Stream them directly into dd; do not gunzip first unless you specifically need the raw image file.

Download on Linux or FreeBSD with resume and retries:

curl -fL --continue-at - --retry 5 --retry-delay 5 --progress-bar -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz
curl -fL --retry 5 --retry-delay 5 -O \
  https://osa.smilepowered.org/downloads/iso/clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz.sha256

Linux:

sha256sum -c clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz.sha256
set -o pipefail 2>/dev/null || true
gzip -dc clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
sync

FreeBSD:

HASH=$(awk '{print $1}' clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz.sha256)
sha256 -c "$HASH" clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz
gzip -dc clawdie-xfce-quindecim-usb-DD.MM.YY.img.gz | sudo dd of=/dev/daX bs=1M status=progress conv=fsync
sync

Replace /dev/sdX or /dev/daX with the whole USB device, not a partition. For the full safety checklist and raw .img variant, see FLASHING.md.

If you built with --live-default-password, the live tty password for clawdie is quindecim. The normal graphical path still uses LightDM autologin.

The image is sparse on the build host. build.sh prints both logical image size and allocated size; write the logical image to a USB key large enough for it.

---

Boot the USB

1. Boot from the USB image.

2. /usr/local/etc/rc.d/clawdie_live_gpu runs before LightDM and selects a conservative live graphics path.

3. The live session starts XFCE and autologins as local user clawdie.

4. A desktop launcher opens the static Clawdie bootstrap page.

5. Confirm the NetworkMgr tray icon appears in the bottom panel, shows interfaces, and can open/join Wi-Fi if needed.

6. Confirm the bottom panel launchers work: Whisker menu, Chromium, pcmanfm, terminal, and volume mixer.

7. Verify the core operator tools:

   pi --help
   tailscale version
   chromium
   tmux -V
   python3 -c "import PIL; print(PIL.__version__)"
   bastille --help
   mdo -u root bastille --help
   test -f /usr/local/share/fonts/dejavu/DejaVuSansMono.ttf
   

8. If you have a Tailscale auth key, join later with FreeBSD mac_do:

   mdo -u root tailscale up
   

Disk deployment, upgrade, rescue, and full Clawdie bootstrap are later phases on this branch.

---

Documentation

• BUILD.md — build flags, cache behavior, and test flow
• FLASHING.md — Linux and FreeBSD USB flashing commands
• REQUIREMENTS.md — build host and deployment requirements
• NETWORKING.md — PF, Tailscale, warden0, and setup access
• TESTING.md — bhyve and hardware validation procedures
• SHELL-ARCHITECTURE.md — firstboot module layout
• SHELL-MODULES.md — module reference
• docs/VPS-MIGRATION.md — VPS/cloud deployment path
• doc/OPERATOR-USB-XFCE-PROPOSAL.md — active branch direction

---

Current Limitations

• USB persistence work is not implemented yet on this branch.
• Disk deployment is intentionally deferred.
• Historical Lumina/QML files remain in-tree but are not the active live-session path.
• NVIDIA on the live USB is intentionally conservative: the image prefers integrated/open graphics first and only uses proprietary NVIDIA modules if a concrete nvidia.ko is installed in the rootfs.
• Provider/model, Telegram, and full Clawdie-AI service bootstrap are intentionally deferred.

---

Last updated: 16.maj.2026