clawdie-iso/REQUIREMENTS.md

Clawdie-ISO Requirements

Pre-install requirements for building and deploying Clawdie-ISO (Unified).

---

Quick Start Checklist

Before building, ensure you have:

• FreeBSD 15.0+ build host
• 128 GB USB key (64 GB minimum)
• Internet connection (10+ Mbps)
• Tailscale auth key (recommended)
• 150 GB free disk space
• 40-60 minutes time

---

Hardware Requirements

Minimum Specifications

Component	Minimum	Recommended	Local LLM	Notes
CPU	4 cores	4+ cores	4+ cores	More cores = faster builds
RAM	8 GB	16 GB	32 GB+	ZFS ARC + jails need RAM
Disk	50 GB	100 GB	256 GB	Disk or USB key
Network	1 Gbps	1 Gbps	1 Gbps	Required for fetch phase

Why 8 GB minimum?

• ZFS ARC cache is RAM-hungry
• 4 jails running (worker, db, git, cms)
• Desktop environment (Lumina) included
• Base system overhead

Why 32 GB for local LLM?

• Ollama loads models into RAM
• 7B model = ~8 GB RAM
• 13B model = ~16 GB RAM
• System still needs RAM for jails + ZFS

Unified ISO

Single ISO works everywhere:

• VPS/Cloud: Desktop disabled automatically (headless mode)
• Baremetal: Desktop enabled automatically (display detected)
• GPU Drivers: All three NVIDIA versions included (390/470/590)

No need to choose target - runtime detection handles configuration.

USB Key Requirements

USB Size	Image Size	Free Space	Use Case
64 GB	50 GB	~14 GB	Minimum (tight)
128 GB	100 GB	~28 GB	Recommended
256 GB	200 GB	~56 GB	Future-proof

Important:

• Do NOT use USB < 64 GB (build will fail)
• USB 3.0 recommended (faster writes)
• Quality matters (avoid cheap USB keys)

USB Speed Comparison

USB Type	Speed	Write Time	Notes
USB 3.0	5 Gbps	~5 min	Recommended
USB 2.0	480 Mbps	~10-15 min	Works but slower
USB 3.1/3.2	10-20 Gbps	~3-5 min	Overkill but fast

---

Network Requirements

Internet Connection

• Required for: Fetch phase (downloads ~8 GB)
• Speed: 10+ Mbps recommended
• Duration: 15-20 minutes
• Optional for: Air-gapped builds (see Offline Build section)

Firewall Rules

During Build:

• Outbound: Allow HTTPS (443), HTTP (80) for package downloads
• Inbound: None required

Post-Install:

• With Tailscale: No inbound ports needed
• Without Tailscale: SSH (22) exposed publicly

DNS

• Working DNS resolution required
• pkg.FreeBSD.org must be resolvable
• codeberg.org must be resolvable (for Clawdie-AI tarball)

---

Tailscale Setup (Recommended)

Why Tailscale?

• Secure remote access without port forwarding
• Works behind NAT, CGNAT, dynamic IPs
• Encrypted WireGuard tunnels
• Free for up to 100 devices
• Multi-device access (phone, laptop, tablet)

Setup Steps

1. Sign up at https://tailscale.com (free, no credit card)

2. Navigate to key generation:

   • Admin console → Settings → Keys
   • Or direct: https://login.tailscale.com/admin/settings/keys

3. Generate auth key:

   • Click "Generate auth key"
   • Check "Reusable" (for multiple deployments)
   • Add description: "Clawdie-ISO builds"
   • Set expiration: 90 days (or custom)
   • Tags: Optional (e.g., "tag:clawdie")
   • Click "Generate key"

4. Copy key (starts with tskey-auth-...)

   • Store securely (it's like a password)
   • You won't be able to see it again

5. Export before building:

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

6. Verify:

   echo $TAILSCALE_AUTHKEY
   # Should show: tskey-auth-...
   

Without Tailscale

• Build continues with warning
• SSH exposed on public port 22
• You are responsible for:
  • Strong passwords
  • SSH hardening (key-only auth, fail2ban)
  • Firewall rules
  • Regular security updates

Not recommended for production deployments.

---

Build Host Requirements

FreeBSD Build Host

• OS: FreeBSD 15.0+
• Packages:

  pkg install curl  # for downloads
  pkg install sudo  # for steps 5-7
  

• Disk space: 150 GB free in tmp/ directory
• Permissions: Root or sudo access for steps 5-7

Post-install Toolchain

The installed host needs a Rust toolchain for native dependencies (SWC, tree-sitter). Install rustup under /opt/clawdie after first boot:

sudo mkdir -p /opt/clawdie/tmp /opt/clawdie/rustup /opt/clawdie/cargo
sudo fetch -o /opt/clawdie/tmp/rustup-init.sh https://sh.rustup.rs
sudo env RUSTUP_HOME=/opt/clawdie/rustup CARGO_HOME=/opt/clawdie/cargo \
  sh /opt/clawdie/tmp/rustup-init.sh -y --profile minimal --default-toolchain stable

Linux Build Host

• NOT SUPPORTED - build.sh requires FreeBSD tools:
  • mdconfig (memory disk configuration)
  • gpart (partitioning)
  • newfs (UFS filesystem)
  • mount_ufs (UFS mount)

Workaround: Use FreeBSD VM for building:

# Example: Use bhyve or VirtualBox
# Install FreeBSD 15.0 in VM
# Install curl
pkg install -y curl

# Install sudo (for build steps 5-7)
pkg install -y sudo

# Add user to wheel group (if not already)
pw groupmod wheel -m $USER

# Configure sudo (optional - allows wheel group to sudo without password)
visudo
# Uncomment: %wheel ALL=(ALL) NOPASSWD: ALL

---

Time Requirements

Build Phases

Phase	Duration	Depends On	Notes
Fetch packages	15-20 min	Network speed	~8 GB download
Build image	10-15 min	CPU + disk	Image creation
Write to USB	5-10 min	USB speed	USB 3.0: 5 min, USB 2.0: 10-15 min
First boot + wizard	10-15 min	Interactive	User input needed
Total	40-60 min

Note: Unified ISO includes all packages (desktop + GPU drivers), so build time is consistent.

---

Pre-Install Checklist

Required

• FreeBSD 15.0+ host available
• 128 GB USB key (or 64 GB minimum)
• Internet connection (10+ Mbps)
• curl installed (pkg install curl)
• Root/sudo access (for steps 5-7)
• 150 GB free disk space in tmp/
• 40-60 minutes uninterrupted time

Recommended

• Tailscale account + auth key generated
• USB 3.0 key (faster writes)
• Quality USB brand (SanDisk, Samsung, Kingston)
• Uninterruptible power supply (UPS)

For Local LLM

• 32+ GB RAM confirmed
• 256 GB USB key
• GPU optional (for future acceleration)

---

Offline/Air-Gapped Builds

Scenario

• Building in isolated network
• No internet access
• Security policy prevents cloud services

Requirements

• Pre-downloaded tmp/ directory from online build
• Alternative package repository (local mirror)
• No Tailscale (you handle security)

Steps

1. On internet-connected host:

   ./build.sh --fetch-only
   tar -czf clawdie-cache.tar.gz tmp/
   # Transfer to air-gapped host
   

2. On air-gapped host:

   tar -xzf clawdie-cache.tar.gz
   ./build.sh --skip-fetch
   

Trade-offs

• No automatic security updates
• Manual package management
• You own the security model
• No Tailscale integration

---

Troubleshooting Common Issues

Issue	Cause	Solution
"Insufficient space on /mnt"	USB < 64 GB	Use 128 GB USB key
"pkg: Cannot access database"	No internet	Connect for fetch phase
"Cannot attach mdconfig"	Not root	Use sudo
Build takes > 60 min	Slow network	Use faster connection
"TAILSCALE_AUTHKEY not set"	Missing key	Optional (warning only)
USB write fails	Bad USB	Try different USB key
"out of memory" during build	< 4 GB RAM	Add more RAM (8+ GB)
ZFS pool import fails	Wrong pool name	Pool should be "clawdie"
SSH connection refused	Firewall	Check PF rules, check port 22

Performance Issues

Symptom	Likely Cause	Fix
Very slow fetch (2+ hours)	Network < 1 Mbps	Use faster connection
Build hangs at step 5	Slow disk	Use SSD, not HDD
USB write takes 30+ min	USB 2.0 + cheap USB	Use USB 3.0 + quality brand
First boot slow (5+ min)	Low RAM	Add more RAM

---

Next Steps

Once requirements are met:

1. Build: See BUILD.md for build instructions
2. Test: See TESTING.md for test procedures
3. Deploy: Boot from USB and follow firstboot wizard

---

Quick Reference

Minimum Viable Setup

FreeBSD 15.0 host
8 GB RAM
50 GB disk (or 128 GB USB 3.0)
10 Mbps internet
curl + sudo installed
40-60 min time

Recommended Setup

FreeBSD 15.0 host
16 GB RAM
100 GB disk (or 128 GB USB 3.0)
25 Mbps internet
Tailscale auth key ready
curl + sudo installed
40-60 min time

Local LLM Setup

FreeBSD 15.0 host
32+ GB RAM
256 GB disk
Tailscale auth key ready
curl + sudo installed
GPU (optional, future acceleration)

---

Questions? See BUILD.md for detailed build steps or TESTING.md for testing procedures.