clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/REQUIREMENTS.md
Sam & Claude 579a8ccd74 build: document Go+Rust build-host toolchains + toolchain-aware preflight 
Go (builds the zot agent) and Rust (builds the Colibri release binaries) are
required on the build host to produce the binaries build.sh stages, but were
undocumented. Add them to REQUIREMENTS.md (build-host only, not the image), and
make the binary-missing preflights note when the matching toolchain (go/cargo)
isn't installed so that case surfaces up front instead of later.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 12:27:17 +02:00

6.1 KiB
Raw Blame History

Clawdie ISO Requirements

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

Quick Checklist

Before building:

  • FreeBSD 15.0+ 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.0+
  • 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