clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/docs/BASTILLE.md
Clawdie 9370f6623d Add Bastille and jail networking docs
2026-03-08 09:18:35 +01:00

4.5 KiB
Raw Blame History

Bastille on FreeBSD 15

This project uses Bastille as the host-side jail manager for Clawdie's FreeBSD runtime.

Recommendation

Start with one plain native FreeBSD jail backed by ZFS. Do not start with VNET, pf NAT, or Tailscale inside the jail until the basic jailed runtime works.

Required Host Assumptions

  • FreeBSD 15 host
  • ZFS pool zroot
  • Bastille installed from packages
  • Clawdie runtime tested on the host first

Recommended bastille.conf

Keep the stock Bastille structure intact and customize only the lines that matter for this host.

#####################
## [ BastilleBSD ] ##
#####################

## Default paths
bastille_prefix="/usr/local/bastille"
bastille_backupsdir="${bastille_prefix}/backups"
bastille_cachedir="${bastille_prefix}/cache"
bastille_jailsdir="${bastille_prefix}/jails"
bastille_releasesdir="${bastille_prefix}/releases"
bastille_templatesdir="${bastille_prefix}/templates"
bastille_logsdir="/var/log/bastille"

## pf configuration path
bastille_pf_conf="/etc/pf.conf"

## Bastille commands directory
bastille_sharedir="/usr/local/share/bastille"

## Bootstrap archives
bastille_bootstrap_archives="base"

## Pkgbase package sets
bastille_pkgbase_packages="base-jail"

## Default timezone
bastille_tzdata="Europe/Ljubljana"

## Default jail resolv.conf
bastille_resolv_conf="/etc/resolv.conf"

## Bootstrap URLs
bastille_url_freebsd="http://ftp.freebsd.org/pub/FreeBSD/releases/"
bastille_url_hardenedbsd="https://installers.hardenedbsd.org/pub/"
bastille_url_midnightbsd="https://www.midnightbsd.org/ftp/MidnightBSD/releases/"

## ZFS options
bastille_zfs_enable="YES"
bastille_zfs_zpool="zroot"
bastille_zfs_prefix="clawdie-runtime"
bastille_zfs_options="-o compress=on -o atime=off"

## Export/Import options
bastille_compress_xz_options="-0 -v"
bastille_decompress_xz_options="-c -d -v"
bastille_compress_gz_options="-1 -v"
bastille_decompress_gz_options="-k -d -c -v"
bastille_compress_zst_options="-3 -v"
bastille_decompress_zst_options="-k -d -c -v"
bastille_export_options=""

## Networking
bastille_network_vnet_type="if_bridge"
bastille_network_loopback="clawdie0"
bastille_network_pf_ext_if="ext_if"
bastille_network_pf_table="clawdie_jails"

bastille_network_shared=""
bastille_network_gateway=""
bastille_network_gateway6=""

## Default Templates
bastille_template_base="default/base"
bastille_template_empty=""
bastille_template_thick="default/thick"
bastille_template_clone="default/clone"
bastille_template_thin="default/thin"
bastille_template_vnet="default/vnet"
bastille_template_vlan="default/vlan"

## Monitoring
bastille_monitor_cron_path="/usr/local/etc/cron.d/bastille-monitor"
bastille_monitor_cron="*/5 * * * * root /usr/local/bin/bastille monitor ALL >/dev/null 2>&1"
bastille_monitor_logfile="${bastille_logsdir}/monitor.log"
bastille_monitor_healthchecks=""

Why These Settings Matter

  • bastille_sharedir must be set, otherwise Bastille cannot find bootstrap.sh
  • bastille_zfs_enable="YES" tells Bastille to create datasets instead of plain directories
  • bastille_zfs_zpool="zroot" matches the active host pool
  • bastille_zfs_prefix="clawdie-runtime" keeps the ZFS namespace project-specific
  • bastille_tzdata="Europe/Ljubljana" makes jail-local time explicit
  • bastille_network_loopback="clawdie0" and bastille_network_pf_table="clawdie_jails" prepare cleaner naming for later network work

Bootstrap

pkg install bastille
bastille bootstrap -p 15.0-RELEASE

Create the First Jail

Use a plain native jail first.

bastille create clawdie-worker 15.0-RELEASE 10.17.89.21
bastille console clawdie-worker

Then verify outbound access from inside the jail:

fetch -qo- https://api.telegram.org >/dev/null && echo ok

Install Runtime Dependencies in the Jail

pkg install -y node npm git python312 gmake
npm install -g @mariozechner/pi-coding-agent

ZFS Layout

With the configuration above, Bastille datasets should appear under:

zroot/clawdie-runtime
zroot/clawdie-runtime/jails
zroot/clawdie-runtime/releases
zroot/clawdie-runtime/templates

Check with:

zfs list | grep clawdie-runtime

Snapshots and Rollback

Snapshot before risky changes:

zfs snapshot zroot/clawdie-runtime/jails/clawdie-worker@fresh

Rollback if needed:

zfs rollback zroot/clawdie-runtime/jails/clawdie-worker@fresh

What Not to Optimize Yet

Do not add these before the plain jailed runtime is proven:

  • VNET
  • pf NAT for jail subnets
  • Tailscale inside the jail
  • Linux jails
  • bhyve VM integration

Those are later architecture layers, not bootstrap requirements.