Clawdie ISO

Unified FreeBSD installer image for Clawdie-AI.

The current ISO boots into a live Lumina/QML installer, installs FreeBSD to disk, then finishes Clawdie setup on the first boot of the installed system.

Current validation target: bootable dev image with BUILD_CHANNEL=dev and bundled Clawdie-AI from main. Public release images should use BUILD_CHANNEL=release and a pinned Clawdie-AI tag.

What You Get

Boot a USB, complete the live installer, reboot once, then finish setup in the controlplane:

FreeBSD 15.0 base system
PF firewall with jail NAT through warden0
Bastille jail substrate and Clawdie service installation
Offline package repository bundled on the USB image
Clawdie-AI tarball with offline node_modules
Live QML installer for disk/user/network handoff
Post-install setup page at http://127.0.0.1:3100/setup
Optional Tailscale remote access for SSH tunneling to the setup page

Provider keys, Telegram, and browser sign-in are configured after first boot through the controlplane setup page, not during ISO install.

Pre-Install Requirements

Build host:

FreeBSD 15.0+
pkg, curl, Node/npm, Qt6 build tools
root or sudo for image assembly (mdconfig, mount, bootcode)
150 GB free build space recommended
64 GB USB key minimum for the default 50 GB image

Optional but strongly recommended:

Tailscale account and auth key (tskey-auth-...) for secure remote SSH
SSH public key for the installed operator account

Tailscale is recommended, not mandatory. If no auth key is supplied, the ISO build continues with a warning and first boot leaves public SSH on port 22 available so the operator can still reach the host.

Quick Start: Build Image

git clone https://codeberg.org/Clawdie/Clawdie-ISO.git
cd Clawdie-ISO

# Recommended for secure remote access after first boot.
export TAILSCALE_AUTHKEY="tskey-auth-..."

# Full build: fetch FreeBSD, packages, Clawdie-AI, then assemble image.
sudo ./build.sh

Useful alternatives:

# Fetch/cache only. Does not assemble an image.
./build.sh --fetch-only

# Reuse cached packages and image inputs.
# Safe for pinned tags/commits. For moving refs, build.sh caches by resolved commit.
sudo ./build.sh --skip-fetch

# Validation build from current Clawdie-AI main.
sudo ./build.sh --clawdie-ref main

# Release build from a pinned Clawdie-AI tag.
BUILD_CHANNEL=release sudo ./build.sh --clawdie-version 0.10.0

The build prints provenance similar to:

ISO     : 0.1.0-dev
FreeBSD : 15.0-RELEASE amd64
Clawdie : main
Clawdie commit: <sha>

It also writes build-manifest.json into the image and onto the installed system under /usr/local/share/clawdie-iso/.

Write to USB

sudo dd if=tmp/output/clawdie-iso-unified-DD.mmm.YYYY.img of=/dev/daX bs=1M status=progress
sudo sync

Replace /dev/daX with the whole USB device, not a partition.

The image is sparse on the build host. build.sh prints both logical image size and allocated size; write the logical image to a USB key large enough for it.

Install on Hardware or VM

Boot from the USB image.
The live session starts Lumina and launches the Clawdie QML installer.
Select install disk and provide identity/access details.
The live commit step runs the FreeBSD install and copies the Clawdie payload.
Reboot from the installed disk.
First boot runs clawdie-firstboot, deploys Clawdie-AI, starts the loopback-bound controlplane, and generates a setup token.

Open setup locally or over an SSH tunnel:

ssh -L 3100:127.0.0.1:3100 clawdie@<tailnet-or-host-ip>

Then open:

http://127.0.0.1:3100/setup

Read the bootstrap token on the installed host:
```
cat /var/db/clawdie-installer/setup-token
```

After setup completes, Clawdie-AI removes or truncates the cleartext token file.

Do not expose port 3100 directly on the public internet. Loopback HTTP is OK; LAN/tailnet exposure should use TLS and allowlisting.

Documentation

BUILD.md — build flags, cache behavior, and test flow
REQUIREMENTS.md — build host and deployment requirements
NETWORKING.md — PF, Tailscale, warden0, and setup access
TESTING.md — bhyve and hardware validation procedures
SHELL-ARCHITECTURE.md — firstboot module layout
SHELL-MODULES.md — module reference
docs/VPS-MIGRATION.md — VPS/cloud deployment path

Current Limitations

ISO live-install path is still under active validation.
Locale/keymap are currently neutral defaults (en_US.UTF-8, us.kbd) until QML exposes operator fields.
Provider/model and Telegram setup are intentionally post-install.
Tailscale is optional; without it, public SSH remains open and must be secured by the operator.

Last updated: 12.maj.2026

4.9 KiB Raw Blame History