🦞 FreeBSD Transition

Comprehensive guide for migrating Clawdie AI from Linux to FreeBSD

Why FreeBSD?

🛡️ Security

  • Jails isolate services by default
  • PF firewall is battle-tested
  • ZFS snapshots for instant rollback
  • Smaller attack surface than Linux

💾 ZFS Native

  • No ZFS-on-Linux workarounds
  • Instant snapshots & clones
  • Built-in compression & dedup
  • Data integrity guaranteed

📦 Jails (Not Docker)

  • Lighter than containers
  • Bastille for easy management
  • Shared kernel, zero overhead
  • Predictable networking

🖥️ bhyve VMs

  • Run Linux VMs when needed
  • Browser automation in VM
  • Native hypervisor
  • ZFS-backed disk images

Warden Network Architecture

┌─────────────────────────────────────────────────────────────────┐ │ FreeBSD Host (controlplane) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────────┐ │ │ │ vtnet0 │ │ tailscale0│ │ warden0 (bridge) │ │ │ │ Public IP│ │ VPN │ │ 10.0.0.1/24 │ │ │ └────┬─────┘ └────┬─────┘ └───────────┬──────────────┘ │ │ │ │ │ │ │ │ │ ┌────────────┼────────────┐ │ │ │ │ │ │ │ │ │ ┌────▼─────┐ ┌────▼────┐ ┌──▼───┐ ┌────▼────┐ ┌────▼───┐│ │ │ nginx │ │ pf │ │db │ │controlplane│ │cms ││ │ │ :80,443 │ │ firewall│ │10.0.0.3│ │10.0.0.100│ │10.0.0.5││ │ └──────────┘ └─────────┘ │postgres│ │operator │ │astro ││ │ └────────┘ └──────────┘ │strapi ││ │ ┌──────────┐ ┌──────────┐ └────────┘│ │ │git │ │ollama │ │ │ │10.0.0.4 │ │10.0.0.6 │ │ │ │code storage │LLM local │ │ │ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────┘

IP Allocation

IPComponentPurpose
10.0.0.1warden0 (bridge)Host gateway for jails
10.0.0.3db jailPostgreSQL + PGVector
10.0.0.4git jailLocal git storage
10.0.0.5cms jailAstro + Strapi
10.0.0.6ollama jailLocal LLM inference
10.0.0.100controlplane jailOperator node, Ansible

Linux → FreeBSD Command Map

Service Management

Linux (systemctl)FreeBSD (service + sysrc)
systemctl start nginxservice nginx start
systemctl enable nginxsysrc nginx_enable=YES
systemctl status nginxservice nginx status
systemctl reload nginxservice nginx reload
systemctl restart nginxservice nginx restart

Package Management

Linux (apt)FreeBSD (pkg)
apt updatepkg update
apt upgradepkg upgrade
apt install nginxpkg install nginx
apt remove nginxpkg delete nginx
apt list --installedpkg info
apt search nginxpkg search nginx
dpkg -L nginxpkg info -l nginx

Networking

LinuxFreeBSD
ip addrifconfig
ip routenetstat -rn
ss -tlnpsockstat -l
iptables -Lpfctl -sr
iptables -t nat -Lpfctl -sn

Shell & Paths

LinuxFreeBSDNotes
/bin/bash/usr/local/bin/bashInstall bash: pkg install bash
/usr/bin/*/usr/local/bin/*User packages go to local
#!/bin/bash#!/usr/bin/env bashUse env for portability

PF Firewall (replaces iptables)

Basic Jail NAT

# /etc/pf.conf
ext_if = "vtnet0"
warden_net = "10.0.0.0/24"

# NAT for jail outbound traffic
nat on $ext_if from $warden_net to any -> ($ext_if)

# Allow jail traffic
pass quick on warden0 inet from $warden_net to any keep state

Port Forward to Jail

# Forward PostgreSQL to controlplane jail (Tailscale only)
rdr pass on tailscale0 proto tcp from any to any port 5432 -> 10.0.0.100
pass in on tailscale0 proto tcp to 10.0.0.100 port 5432

# Forward HTTP to nginx on host
pass in on $ext_if proto tcp to ($ext_if) port { 80, 443 }

PF Commands

ActionCommand
Validate configpfctl -nf /etc/pf.conf
Reload rulesservice pf reload
Show rulespfctl -sr
Show NATpfctl -sn
Show state tablepfctl -ss
Enable PFsysrc pf_enable=YES && service pf start

Bastille Jail Management

Basic Commands

# List jails
bastille list

# Create thick jail (recommended)
bastille create -T -B -g 10.0.0.1 controlplane 15.0-RELEASE 10.0.0.100/24 warden0

# Start/Stop/Restart
bastille start controlplane
bastille stop controlplane
bastille restart controlplane

# Enter jail console
bastille console controlplane

# Run command in jail
bastille cmd controlplane pkg install nginx

# Destroy jail (careful!)
bastille destroy controlplane

Low-level Jail Commands

# List running jails
jls

# Run command in jail by name
jexec controlplane pkg install bash

# Run command in jail by JID
jexec 1 service nginx status

Key Configuration Files

/etc/rc.conf (use sysrc)

# System
hostname="controlplane.clawdie.si"
zfs_enable="YES"

# Networking for jails
gateway_enable="YES"
cloned_interfaces="bridge0"
ifconfig_bridge0_name="warden0"
ifconfig_warden0="inet 10.0.0.1/24 up"

# Security
sshd_enable="YES"
pf_enable="YES"

# Services
nginx_enable="YES"
bastille_enable="YES"
rctl_enable="YES"

/boot/loader.conf

# ZFS support
zfs_load="YES"

# Bhyve virtualization
vmm_load="YES"
nmdm_load="YES"

# Resource controls for jails
kern.racct.enable=1

# Headless boot
beastie_disable="YES"
autoboot_delay="-1"

# ZFS ARC limit (4GB)
vfs.zfs.arc_max="4294967296"
Tip: Use sysrc to modify rc.conf, never edit by hand in scripts. Example: sysrc nginx_enable=YES

OpenClaw on FreeBSD - Compatibility

ComponentRiskNotes
Node.js LOW Available via pkg install node24
tmux LOW Available via pkg install tmux
ZFS LOW Native support, better than Linux
Shell scripts MEDIUM Check #!/bin/bash paths, use #!/usr/bin/env bash
System commands MEDIUM ps, netstat, ifconfig have different flags
npm native modules MEDIUM Some packages use node-gyp with Linux assumptions
OpenClaw core MEDIUM Not tested on FreeBSD, may need patches

Recommended Approach

  1. Phase 1: Run OpenClaw in controlplane jail (isolated)
  2. Phase 2: Test all features, identify issues
  3. Phase 3: Patch or run problematic components in Linux VM (bhyve)
Fallback: If OpenClaw doesn't work natively, run it in a Debian VM via bhyve. The VM can access the same ZFS storage and network.

FreeBSD Skills in Clawdie-AI Repo

SkillPurpose
freebsd-adminHost-level changes (sysrc, service, sysctl)
ansible-freebsdRepeatable automation via Ansible playbooks
warden-bootstrapBastille jail creation (controlplane)
warden-pfPF firewall rules for jails
warden-zfsZFS dataset layout for jails
bastille-networkBridge networking setup
browser-vmLinux browser VM on bhyve
nginxReverse proxy configuration
postgres-memoryPostgreSQL + PGVector in jail

Quick Reference Commands

# Check FreeBSD version
freebsd-version

# System info
uname -a

# CPU info
sysctl hw.model hw.ncpu

# Memory
sysctl hw.realmem

# Disk usage
df -h

# ZFS status
zpool status
zfs list

# What's listening
sockstat -l

# Find package for file
pkg which /path/to/file

# Check config syntax
sysrc -c nginx_enable

# Enable IP forwarding (for jails)
sysrc gateway_enable=YES
sysctl net.inet.ip.forwarding=1

# Create jail bridge
sysrc cloned_interfaces+=bridge0
sysrc ifconfig_bridge0_name=warden0
sysrc ifconfig_warden0="inet 10.0.0.1/24 up"

⚠️ Common Gotchas