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

1. Boot from the USB image.

2. The live session starts Lumina and launches the Clawdie QML installer.

3. Select install disk and provide identity/access details.

4. The live commit step runs the FreeBSD install and copies the Clawdie payload.

5. Reboot from the installed disk.

6. First boot runs clawdie-firstboot, deploys Clawdie-AI, starts the loopback-bound controlplane, and generates a setup token.

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

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