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

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

## Canonical Service Jails

Default fixed service slots:

- `db` on `<subnet>.3`
- `cms` on `<subnet>.4`
- `llama-cpp` on `<subnet>.5` (llama-server, embeddings)
- `git` on `<subnet>.6`

The operator controlplane is not a jail in the current model. It runs on the
FreeBSD host and is published at `ai.<internal_base>`.

Example bring-up for the default install:

```sh
bastille create -T -B -g <subnet>.1 db 15.0-RELEASE <subnet>.3/24 warden0
bastille create -T -B -g <subnet>.1 cms 15.0-RELEASE <subnet>.4/24 warden0
bastille create -T -B -g <subnet>.1 git 15.0-RELEASE <subnet>.6/24 warden0
```

Apply internal hostnames after creation:

```sh
bastille config cms set host.hostname cms.home.arpa
bastille config git set host.hostname git.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:

```sh
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 and the Astro/Starlight web baseline; optional Strapi
  content/bootstrap remains internal and deployment-specific

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:

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

## Snapshots

Snapshot persistent service jails before risky changes, for example:

```sh
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
- shared internal surfaces named by role: `ai`, `cms`, `git`
- public web serving delegated to the `cms` jail instead of host nginx ownership