clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/REQUIREMENTS.md
Sam & Claude 95aec991f0 docs: add REQUIREMENTS.md with pre-install checklist (Sam & Claude) 
Comprehensive pre-install requirements guide:

Hardware requirements:
- RAM: 8 GB minimum (ZFS + jails), 16 GB recommended, 32 GB for LLM
- Disk: 64 GB USB minimum, 128 GB recommended, 256 GB for LLM
- CPU: 2 cores minimum, 4+ recommended

Network requirements:
- 10+ Mbps internet for fetch phase
- DNS must resolve pkg.FreeBSD.org
- Firewall rules documented

Tailscale setup:
- Inline instructions for auth key generation
- Without-Tailscale warnings
- Security implications explained

Build host requirements:
- FreeBSD 15.0+ (Linux not supported)
- 150 GB free disk space
- curl + doas/sudo packages

Time estimates:
- Fetch: 15-20 min (network dependent)
- Build: 10-15 min (CPU dependent)
- Write: 5-10 min (USB 3.0)
- First boot: 10-15 min
- Total: 40-60 min

USB requirements:
- USB 3.0 recommended (5 min write)
- USB 2.0 works but slower (10-15 min write)
- Quality brands recommended

Additional sections:
- Pre-install checklist
- Target-specific requirements (baremetal vs vps)
- Offline/air-gapped build instructions
- Troubleshooting common issues
- Quick reference for minimal/recommended/LLM setups
2026-06-04 20:04:22 +02:00

8.7 KiB
Raw Blame History

Clawdie-ISO Requirements

Pre-install requirements checklist for building and deploying Clawdie-ISO.

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 2 cores 4+ cores 4+ cores More cores = faster builds
RAM 8 GB 16 GB 32 GB+ ZFS ARC + jails need RAM
Disk 64 GB USB 128 GB USB 256 GB USB USB key or internal
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)
  • 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

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

Target-Specific Requirements

Target RAM Disk Use Case
baremetal 8+ GB 128 GB USB Desktop + jails
vps 4+ GB 20 GB VPS Headless, minimal
baremetal + LLM 32+ GB 256 GB USB Local AI models

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:

  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+ (14.2 minimum)
  • Packages: 
    pkg install curl  # for downloads
pkg install doas   # or sudo (for steps 5-7)
  • Disk space: 150 GB free in tmp/ directory
  • Permissions: Root or doas/sudo access for steps 5-7

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, doas
# Clone clawdie-iso repo
# Build inside VM

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

Breakdown by Target

Target Fetch Build Write First Boot Total
baremetal 15-20 min 10-15 min 5-10 min 15-20 min 45-65 min
vps 10-15 min 5-10 min N/A 5-10 min 20-35 min

Note: VPS builds are faster (no desktop packages, fewer GPU drivers).

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/doas 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 VPS Builds

  • Assistant name decided (e.g., "Clawdie", "Natasha")
  • Domain decided (e.g., "clawdie.example.com")
  • Timezone known (e.g., "Europe/Ljubljana")

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 doas or 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
128 GB USB 3.0
10 Mbps internet
curl + doas installed
40-60 min time

Recommended Setup

FreeBSD 15.0 host
16 GB RAM
128 GB USB 3.0 (SanDisk/Samsung)
25 Mbps internet
Tailscale auth key ready
curl + doas installed
40-60 min time

Local LLM Setup

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

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