clawdie-iso/skills/build-iso/SKILL.md

name	version	description
build-iso	0.0.1	Build and publish a Clawdie-AI USB installer ISO image for download from the nginx downloads endpoint

build-iso — USB Installer Build Skill

Overview

Rebuilds the Clawdie-AI USB installer image from the latest clawdie-iso commits and publishes it to the nginx downloads endpoint so it can be downloaded from:

https://<AGENT_DOMAIN>/downloads/clawdie-iso-latest.img

The clawdie-iso repo is mirrored into the git jail during setup. The agent clones a working copy from the jail, runs build.sh, and copies the output to the CMS jail nginx webroot downloads folder.

Trigger phrases

• "build iso"
• "rebuild installer"
• "create usb installer"
• "publish iso"
• "update the download"
• "latest iso"

Requirements

• Git jail running (jls shows <AGENT_NAME>-git)
• CMS jail running with nginx (jls shows <AGENT_NAME>-cms)
• Internet access from the host (build.sh fetches FreeBSD memstick + packages)
• ~8 GB free disk space on host for build working directory
• Root or sudo for build.sh (uses mdconfig, mount) — see Privilege note

v0.0.1 limitation — Privilege: build.sh requires root for disk image operations. In v0.0.1 the agent runs the build as root via the hostd socket (exec operation). The hostd whitelisted command is iso-build. If hostd does not yet have this operation, fall back to: ask the operator to run scripts/build-iso.sh manually as root.

Planned for v0.0.2: add iso-build as a formal hostd operation with full privilege delegation, removing the need for manual fallback.

Architecture

agent (worker jail)
  → hostd socket → iso-build op (host, root)
      → git clone from git jail (/srv/git/clawdie-iso.git)
      → build.sh (fetches, injects, repacks)
      → cp output → cms jail webroot /downloads/
      → return download URL

Nginx downloads endpoint

The CMS jail nginx must have a /downloads/ location block. This is set up during the first ISO build if not already present:

location /downloads/ {
    alias /usr/local/www/<AGENT_DOMAIN>/downloads/;
    autoindex on;
    add_header Content-Disposition 'attachment';
}

Create the directory inside the CMS jail:

jexec <AGENT_NAME>-cms install -d -m 0755 /usr/local/www/<AGENT_DOMAIN>/downloads

Procedure

Step 1 — Get latest clawdie-iso from git jail

# On host, clone from git jail's bare repo into a working directory
git clone file:///usr/local/bastille/jails/<AGENT_NAME>-git/root/srv/git/clawdie-iso \
    ./tmp/clawdie-iso-build

# Or update an existing clone
git -C ./tmp/clawdie-iso-build pull

Step 2 — Run build.sh

cd ./tmp/clawdie-iso-build
sudo ./build.sh
# Output: tmp/output/clawdie-iso-<variant>-DD.mmm.YYYY.img (~4-8 GB)

Monitor progress — build takes 15–40 minutes depending on bandwidth (fetching FreeBSD memstick + packages). Use --skip-fetch if packages are already cached:

sudo ./build.sh --skip-fetch

Step 3 — Publish to nginx downloads

# Copy into CMS jail webroot
sudo cp ./tmp/clawdie-iso-build/tmp/output/clawdie-iso-*.img \
    /usr/local/bastille/jails/<AGENT_NAME>-cms/root/usr/local/www/<AGENT_DOMAIN>/downloads/clawdie-iso-latest.img

# Symlink with date stamp for archive
sudo ln -sf clawdie-iso-latest.img \
    "/usr/local/bastille/jails/<AGENT_NAME>-cms/root/usr/local/www/<AGENT_DOMAIN>/downloads/clawdie-iso-$(LC_TIME=C date +%d.%b.%Y | tr 'A-Z' 'a-z').img"

Step 4 — Verify and report

# Confirm file is accessible
curl -I https://<AGENT_DOMAIN>/downloads/clawdie-iso-latest.img

Report the download URL and file size to the operator.

Cleanup

# Remove build working directory after successful publish
rm -rf ./tmp/clawdie-iso-build

The tmp/cache/ directory inside the build tree is gitignored and expensive to re-fetch. If disk space permits, keep it: sudo ./build.sh --skip-fetch on the next run will be significantly faster.

Troubleshooting

Symptom	Cause	Fix
mdconfig: no devices left	Too many loopback devices open	mdconfig -d -u X to free stale devices
pkg repo fails	tmp/packages/ is empty	Re-run without --skip-fetch
nginx 404 on /downloads/	Location block missing	Add location block (see above), reload nginx
Checksum mismatch on memstick	Interrupted download	Delete tmp/cache/FreeBSD-*.img and rebuild
git clone from jail fails	Git jail not running	bastille start <AGENT_NAME>-git

Version history

Version	Date	Changes
0.0.1	2026-03-17	Initial skill — manual/hostd fallback build, nginx publish procedure