clawdie-iso/REQUIREMENTS.md

Clawdie ISO Requirements

Build and test requirements for the current unified Clawdie operator USB branch.

---

Quick Checklist

Before building:

• FreeBSD 15.x build host
• 150 GB free build space recommended
• 32 GB USB key minimum (IMAGE_SIZE=28G)
• Internet access for fetch phase
• root or sudo for image assembly

Before booting/testing:

• Browser/network test target in mind
• pi is part of the verification checklist

---

Build Host Requirements

Operating System

• FreeBSD 15.x
• ZFS recommended for comfortable build storage, but not required by build.sh

Packages

Install the baseline tools:

sudo pkg install -y curl node24 npm-node24 sudo go rust

go and rust are build-host toolchains, not image packages: go builds the zot agent binary and rust builds the Colibri release binaries. build.sh stages those prebuilt binaries (it does not compile them itself) and fails preflight if they are missing — so build them on the host first. They are not installed onto the image.

build.sh sets its own FreeBSD tool PATH:

/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

This keeps fetch/build behavior independent from the invoking user's login PATH.

Disk Space

Item	Typical size
FreeBSD memstick cache	~2 GB
Offline pkg repository	varies
Clawdie-AI offline tarball	varies
Working image	28 GB sparse
Output image	28 GB sparse

Recommended free space: 150 GB.

USB Key

USB size	Image size	Status
32 GB	28 GB	minimum
64 GB	50 GB	optional
128 GB	100 GB	recommended
256 GB	200 GB	comfortable

Do not use a USB key smaller than the logical image size printed by build.sh.

---

Network Requirements

During Build

Outbound access:

• HTTPS/HTTP to FreeBSD package mirrors
• HTTPS to Codeberg for Clawdie-AI tarballs
• HTTPS to npm registry for bundled npm CLI tarballs

Inbound access: none.

During Live USB Use

Tailscale is recommended but optional.

With a Tailscale auth key:

• operator can join the tailnet from the live USB
• remote operator access becomes easier
• later deployment phases can reuse that connectivity

Without a Tailscale auth key:

• the USB still boots and remains usable locally
• operator can authenticate Tailscale later with mdo -u root tailscale up

For local networking, the live USB now bundles the broad native wifi-firmware-kmod package set plus FreeBSD-fwget. The intended first-pass model is still:

• native driver + firmware exposes a real wlan device
• NetworkMgr manages that interface
• Ethernet or USB tethering remain fallback paths

wifibox is intentionally not part of the current operator-USB plan.

---

Target Machine Requirements

Minimum Operator USB Hardware

Component	Minimum	Recommended	Notes
CPU	4 cores	4+ cores	More helps browser and future deploy
RAM	8 GB	16 GB+	XFCE + Firefox are the main loads
Disk	32 GB	64 GB+	28 GB image fits common sticks
Network	1 NIC	1 Gbps	Needed for remote operation

Local AI models require substantially more disk/RAM and are optional.

Display

The current branch expects a graphical XFCE session. Headless/server flows are not the target for this operator USB milestone.

The live USB now chooses graphics conservatively at boot:

• Intel -> i915kms
• AMD/ATI -> amdgpu with radeonkms best-effort
• VMware -> vmwgfx
• NVIDIA -> proprietary modules only if a concrete nvidia.ko is present in the live rootfs
• otherwise -> Xorg fallback path (scfb / vesa)

This favors broad boot success over guaranteed proprietary NVIDIA acceleration.

---

Tailscale Auth Key

Generate a key at:

https://login.tailscale.com/admin/settings/keys

Recommended options:

• reusable key for repeated test installs
• expiration appropriate for the test window
• optional tag if your tailnet policy uses tags

Authenticate from the running USB later with:

mdo -u root tailscale up

Future persistence work may add a first-boot key entry flow alongside the other operator/API key collection steps.

---

Current Phase Boundaries

This branch is intentionally narrower than the older disk-installer flow.

Included now:

• XFCE desktop
• browser
• Tailscale package
• bundled pi

Deferred:

• full Clawdie-AI service graph on USB
• disk deployment
• upgrade/rescue workflow
• post-install setup token flow
• provider/model and Telegram setup flow

---

Build Commands

# full validation build
sudo ./build.sh

# fetch-only cache refresh
./build.sh --fetch-only

# assemble cached inputs
sudo ./build.sh --skip-fetch

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

---

Common Problems

Symptom	Likely cause	Fix
missing package archive	stale tmp/packages cache	run sudo ./build.sh
pkg not found in normal shell	user PATH lacks /usr/local/sbin	update PATH; build script already guards
cannot attach md device	not root / stale md device	run with sudo; clean stale mdconfig
no browser on desktop	live package install failed	rerun full build; inspect pkg stage
Tailscale not authenticated	expected before operator login	run mdo -u root tailscale up from the USB
USB still shows old ZFS label	stale end-of-disk metadata	wipe whole stick before reflashing

---

Last updated: 16.maj.2026