579a8ccd74
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>
224 lines
6.1 KiB
Markdown
224 lines
6.1 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
# 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
|