skill: add clawdie-iso-build — operational surface of build.sh
Covers: canonical command with FEATURE_COLIBRI=YES, flag matrix with cache dependencies, pre-flight checklist, build steps overview, tmux usage for long builds, --live-default-password, and common pitfalls. Distilled from 2026-06-22 build session on OSA.
This commit is contained in:
parent
e013f32145
commit
19375ef0d7
1 changed files with 160 additions and 0 deletions
160
skills/clawdie-iso-build/SKILL.md
Normal file
160
skills/clawdie-iso-build/SKILL.md
Normal file
|
|
@ -0,0 +1,160 @@
|
||||||
|
---
|
||||||
|
name: clawdie-iso-build
|
||||||
|
description: Build the Clawdie operator USB ISO — command-line flags, cache management, pre-flight checks, and pitfalls. Covers the operational surface of build.sh (not the shell implementation).
|
||||||
|
category: freebsd
|
||||||
|
triggers:
|
||||||
|
- "build iso"
|
||||||
|
- "rebuild iso"
|
||||||
|
- "clawdie image"
|
||||||
|
- "operator usb"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Clawdie ISO Build
|
||||||
|
|
||||||
|
Use this when building or rebuilding the Clawdie operator USB image. This skill
|
||||||
|
covers the **operational surface** — flags, caches, pre-reqs, pitfalls. For
|
||||||
|
implementation details, read `build.sh` directly.
|
||||||
|
|
||||||
|
## Repo
|
||||||
|
|
||||||
|
```
|
||||||
|
/home/clawdie/ai/clawdie-iso
|
||||||
|
```
|
||||||
|
|
||||||
|
## Canonical build command
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /home/clawdie/ai/clawdie-iso
|
||||||
|
sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password
|
||||||
|
```
|
||||||
|
|
||||||
|
This produces a bootable XFCE ISO with:
|
||||||
|
- `clawdie` user (password: `quindecim` — the FreeBSD 15 codename)
|
||||||
|
- Colibri daemon + zot agent staged and ready
|
||||||
|
- `START-HERE.txt` auto-opened in Mousepad on first login (bootstrap autostart)
|
||||||
|
- BW secrets instructions already in START-HERE.txt
|
||||||
|
|
||||||
|
## Build flags
|
||||||
|
|
||||||
|
| Flag | Effect | Cache required |
|
||||||
|
|------|--------|---------------|
|
||||||
|
| *(none)* | Full build: fetch memstick + packages + assemble | Nothing |
|
||||||
|
| `--skip-memstick-fetch` | Skip step 1 (1.5G FreeBSD download) | `tmp/cache/FreeBSD-*.img` |
|
||||||
|
| `--skip-fetch` | Skip steps 2+4 (packages + clawdie-ai tarball) | `tmp/packages/` + `tmp/cache/clawdie-ai-*.tar.gz` |
|
||||||
|
| `--live-default-password` | Set clawdie password to `quindecim` | — |
|
||||||
|
| `--clawdie-password <pw>` | Set explicit clawdie password | — |
|
||||||
|
| `--root-password <pw>` | Set explicit root password | — |
|
||||||
|
| `--fetch-only` | Download only, no assembly (no root needed) | — |
|
||||||
|
|
||||||
|
**Fastest rebuild** (after first build populates caches):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password \
|
||||||
|
--skip-memstick-fetch --skip-fetch
|
||||||
|
```
|
||||||
|
|
||||||
|
Skips all downloads — goes directly to image assembly (step 5).
|
||||||
|
|
||||||
|
## FEATURE_COLIBRI gate
|
||||||
|
|
||||||
|
`FEATURE_COLIBRI=YES` enables the full agent stack. Default is `NO` (basic
|
||||||
|
XFCE ISO without agents). When YES:
|
||||||
|
|
||||||
|
| What gets staged | Source |
|
||||||
|
|-----------------|--------|
|
||||||
|
| `colibri-daemon` | `COLIBRI_REPO/target/release/` (default: `/home/clawdie/ai/colibri/target/release/`) |
|
||||||
|
| `colibri`, `colibri-mcp` | same |
|
||||||
|
| `colibri-test-agent` | same (if `COLIBRI_STAGE_TEST_AGENT=YES`) |
|
||||||
|
| `zot` binary | `ZOT_REPO/bin/` (default: `/home/clawdie/ai/zot/bin/`) |
|
||||||
|
| `colibri_daemon` rc.d | `packaging/freebsd/colibri_daemon.in` |
|
||||||
|
| `provider.env` template | auto-generated with Vaultwarden URL |
|
||||||
|
|
||||||
|
Related vars in `build.cfg`:
|
||||||
|
- `COLIBRI_REPO` — path to colibri checkout (default: `/home/clawdie/ai/colibri`)
|
||||||
|
- `ZOT_REPO` — path to zot checkout (default: `/home/clawdie/ai/zot`)
|
||||||
|
- `ZOT_VERSION` — zot git tag (default: `v0.2.29`)
|
||||||
|
- `COLIBRI_STAGE_AGENT` — stage agent (default: `YES`)
|
||||||
|
- `COLIBRI_STAGE_TEST_AGENT` — stage test agent (default: `NO`)
|
||||||
|
|
||||||
|
## Pre-flight checklist
|
||||||
|
|
||||||
|
Before running the build, verify:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Colibri release binaries exist (needed only if FEATURE_COLIBRI=YES)
|
||||||
|
ls -la /home/clawdie/ai/colibri/target/release/colibri-daemon \
|
||||||
|
/home/clawdie/ai/colibri/target/release/colibri \
|
||||||
|
/home/clawdie/ai/colibri/target/release/colibri-mcp
|
||||||
|
|
||||||
|
# If missing, build them:
|
||||||
|
# cd /home/clawdie/ai/colibri && cargo build --workspace --release
|
||||||
|
|
||||||
|
# 2. zot at correct version
|
||||||
|
cd /home/clawdie/ai/zot && git checkout v0.2.29 && make build
|
||||||
|
|
||||||
|
# 3. Disk space (need ~12G for build)
|
||||||
|
df -h / | grep -v Filesystem # should show >15G avail
|
||||||
|
|
||||||
|
# 4. Repo clean (required for BUILD_CHANNEL=release, optional for dev)
|
||||||
|
cd /home/clawdie/ai/clawdie-iso && git status -sb
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build steps overview
|
||||||
|
|
||||||
|
Build takes 30-60 minutes. Steps:
|
||||||
|
|
||||||
|
| Step | What | Skipped by |
|
||||||
|
|------|------|-----------|
|
||||||
|
| 1/7 | Fetch FreeBSD memstick (1.5G) | `--skip-memstick-fetch` |
|
||||||
|
| 2/7 | Fetch packages to `tmp/packages/` | `--skip-fetch` |
|
||||||
|
| 3/7 | Generate pkg repo metadata | `--skip-fetch` |
|
||||||
|
| 4/7 | Fetch clawdie-ai tarball | `--skip-fetch` |
|
||||||
|
| 5/7 | Prepare working image (mdconfig, mount) | — |
|
||||||
|
| 6/7 | Inject payload (packages, configs, agent stack) | — |
|
||||||
|
| 7/7 | Write output to `tmp/output/` | — |
|
||||||
|
|
||||||
|
Output: `tmp/output/clawdie-quindecim-<version>.img` (+ `.sha256` + manifest)
|
||||||
|
|
||||||
|
## Running the build
|
||||||
|
|
||||||
|
Build requires root (mdconfig, mount, pkg). Always use `sudo`. The build takes
|
||||||
|
30-60 minutes — use tmux, not `terminal(background=true)` (doesn't work on
|
||||||
|
FreeBSD).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start in tmux window 1:3 (the dedicated iso window)
|
||||||
|
tmux send-keys -t 1:3 'cd /home/clawdie/ai/clawdie-iso && sudo FEATURE_COLIBRI=YES ./build.sh --live-default-password' Enter
|
||||||
|
|
||||||
|
# Monitor progress
|
||||||
|
tmux capture-pane -t 1:3 -p | tail -10
|
||||||
|
```
|
||||||
|
|
||||||
|
Tmux window `1:3` is named "iso" and is pre-configured for builds.
|
||||||
|
|
||||||
|
## After build
|
||||||
|
|
||||||
|
The output image is in `tmp/output/`. The bootstrap experience:
|
||||||
|
1. Boots to XFCE desktop
|
||||||
|
2. `clawdie` user auto-logged in (password: `quindecim`)
|
||||||
|
3. `START-HERE.txt` opens in Mousepad — contains BW secrets setup instructions
|
||||||
|
4. Colibri daemon starts via rc.d
|
||||||
|
5. User adds 3 BW secrets to `/usr/local/etc/colibri/provider.env`, restarts daemon
|
||||||
|
|
||||||
|
## Pitfalls
|
||||||
|
|
||||||
|
- **Must run as root.** `sudo` required. The build uses mdconfig, mount, pkg.
|
||||||
|
- **Use tmux, not background.** `terminal(background=true)` doesn't work on
|
||||||
|
FreeBSD. Use `tmux send-keys -t 1:3` for long builds.
|
||||||
|
- **`--skip-fetch` needs cached packages.** If `tmp/packages/All/` is empty
|
||||||
|
or stale, the build fails at step 3. Run without `--skip-fetch` first to
|
||||||
|
populate caches.
|
||||||
|
- **`--skip-memstick-fetch` needs cached memstick.** If `tmp/cache/FreeBSD-*.img`
|
||||||
|
is missing, build fails. The memstick rarely changes between builds.
|
||||||
|
- **zot version matters.** `build.sh` preflight checks for `-x zot`. If the
|
||||||
|
binary exists but is stale (wrong version), it won't catch it — the version
|
||||||
|
is only recorded in the manifest. Always `git checkout v0.2.29 && make build`
|
||||||
|
before building.
|
||||||
|
- **Colibri binaries must be in `target/release/`.** Debug builds won't work.
|
||||||
|
Run `cargo build --workspace --release` first.
|
||||||
|
- **Password flag is easy to forget.** Without `--live-default-password`, the
|
||||||
|
clawdie account has no password set — requires root to fix.
|
||||||
Loading…
Add table
Reference in a new issue