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.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