clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/REQUIREMENTS.md

5.7 KiB
Raw Blame History

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 /login with Codex/OpenAI subscription auth

Peer supported options include 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