clawdie-ai/docs/public/architecture/bastille.md

title
Bastille on FreeBSD 15

Clawdie uses Bastille as the host-side jail manager for its Warden runtime on FreeBSD.

Host Assumptions

• FreeBSD 15 host
• ZFS root pool
• Bastille installed from packages
• warden0 bridge on 10.0.0.1/24
• host-side orchestration, not an operator jail

Recommendation

Keep Bastille boring and explicit:

• bootstrap 15.0-RELEASE
• keep the stock Bastille layout
• use warden0 as the canonical bridge name
• use 10.0.0.0/24 as the default internal jail subnet
• create persistent service jails as thick VNET jails
• create workers as thin jails from the current profile logic

Bootstrap

pkg install -y bastille
bastille bootstrap -p 15.0-RELEASE

Canonical Service Jails

Default fixed service slots:

• controlplane on 10.0.0.2
• db on 10.0.0.3
• cms on 10.0.0.4
• llama-cpp on 10.0.0.5 (llama-server, embeddings)

Example bring-up for the default clawdie install:

bastille create -T -B -g 10.0.0.1 clawdie-controlplane 15.0-RELEASE 10.0.0.2/24 warden0
bastille create -T -B -g 10.0.0.1 clawdie-db 15.0-RELEASE 10.0.0.3/24 warden0
bastille create -T -B -g 10.0.0.1 clawdie-cms 15.0-RELEASE 10.0.0.4/24 warden0

Apply internal hostnames after creation:

bastille config clawdie-controlplane set host.hostname controlplane.clawdie.home.arpa
bastille config clawdie-db set host.hostname db.clawdie.home.arpa
bastille config clawdie-cms set host.hostname cms.clawdie.home.arpa

Worker Bring-Up

Workers are derived from AGENT_NAME and start in the high range:

• default worker: 10.0.0.101
• future networked workers continue upward from there

Use the setup path rather than hand-writing worker create commands:

just setup -- --step jails --create

Networking

The intended host-side network is:

• bridge: warden0
• gateway: 10.0.0.1
• jailed subnet: 10.0.0.0/24

If a VNET jail comes up without a default route, treat that as a provisioning defect and fix the create command rather than applying ad hoc routes later.

Packages and Roles

Current setup steps own the jail bootstrap contract:

• db installs PostgreSQL + pgvector
• git installs plain git storage
• cms installs nginx, Astro baseline, and repo-owned Strapi seed bootstrap

Do not bootstrap a separate operator jail. The FreeBSD host is the operator surface.

ZFS Layout

With the default Bastille + Clawdie settings, datasets should live under a project prefix such as:

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

Snapshots

Snapshot persistent service jails before risky changes, for example:

zfs snapshot zroot/clawdie-runtime/jails/clawdie-db@pre-schema-14.mar.2026-1200
zfs snapshot zroot/clawdie-runtime/jails/clawdie-cms@pre-strapi-14.mar.2026-1230

Use user-facing snapshot names in DD.mmm.YYYY-HHMM format.

Current Direction

• host orchestrator on FreeBSD
• Bastille-managed service and worker jails
• no dedicated operator jail in the active model
• public web serving delegated to the cms jail instead of host nginx ownership