clawdie-iso/REQUIREMENTS.md

Clawdie ISO Requirements

Build and deployment requirements for the current unified Clawdie ISO.

---

Quick Checklist

Before building:

• FreeBSD 15.0+ build host
• 150 GB free build space recommended
• 64 GB USB key minimum (IMAGE_SIZE=50G)
• Internet access for fetch phase
• root or sudo for image assembly
• optional Tailscale auth key for secure remote access

Before installing:

• Target disk selected and safe to erase
• Operator SSH public key available, if using key auth
• Tailscale auth key available, if remote first setup should be tailnet-only
• Provider/model choice ready for post-install /setup

---

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:

sudo pkg install -y curl node24 npm-node24 qt6-base qt6-declarative qt6-buildtools sudo

build.sh sets its own FreeBSD tool PATH:

/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	50 GB sparse
Output image	50 GB sparse

Recommended free space: 150 GB.

USB Key

USB size	Image size	Status
64 GB	50 GB	minimum
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 Install / First Boot

Tailscale is recommended but optional.

With a Tailscale auth key:

• first boot joins the tailnet
• PF allows SSH on tailscale0
• public SSH is blocked after Tailscale is authenticated
• operator reaches setup through SSH tunneling to host loopback

Without a Tailscale auth key:

• install still proceeds
• public SSH on port 22 remains available
• operator is responsible for network exposure and SSH hardening

The controlplane setup page should be reached locally or through a tunnel:

ssh -L 3100:127.0.0.1:3100 clawdie@<host>

Then open:

http://127.0.0.1:3100/setup

Do not expose port 3100 directly on the public internet.

---

Target Machine Requirements

Minimum Runtime Hardware

Component	Minimum	Recommended	Notes
CPU	4 cores	4+ cores	More helps jail provisioning
RAM	8 GB	16 GB+	ZFS + jails + Chromium
Disk	50 GB	100 GB+	More for datasets and caches
Network	1 NIC	1 Gbps	Needed for remote operation

Local AI models require substantially more disk/RAM and are optional.

Display

The live installer uses a graphical Lumina/QML session. Headless/server flows are still under active validation; use bhyve/console access for testing.

---

Tailscale Auth Key

Generate a key at:

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

Export before build if you want it baked into the image environment:

export TAILSCALE_AUTHKEY="tskey-auth-..."

You can also enter/paste the key in the live installer if the UI path exposes it for that build.

---

Post-Install Setup Requirements

Provider keys and Telegram are no longer install-time requirements.

After first boot, the installed system creates a one-time bootstrap token at:

/var/db/clawdie-installer/setup-token

Use it at:

http://127.0.0.1:3100/setup

Recommended provider path:

• Pi interactive /login command with ChatGPT Plus/Pro (Codex) subscription

Also supported: OpenAI API, Anthropic, z.ai, OpenRouter, Gemini, Groq, DeepSeek, Azure OpenAI, Ollama, and other Pi-supported providers.

Telegram setup is optional and happens after a provider is configured.

---

Build Commands

# 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
setup page unreachable remotely	no tunnel / PF boundary	use SSH tunnel to 127.0.0.1:3100
no Tailscale key	optional remote-access choice	continue with public SSH or rebuild

---

Last updated: 12.maj.2026