Skip to content
Clawdie Clawdie

FreeBSD Jail Implementation Guide

This document describes the current Clawdie jail layout on FreeBSD.

Current model

Section titled “Current model”

Clawdie is host-first on current main.

  • the host runs onboarding, orchestration, service management, and verification
  • persistent jails provide isolated shared service roles
  • worker jails run agent tasks
  • there is no active dedicated operator jail
  • the root install is shared platform state, not tenant zero

Identity model

Section titled “Identity model”
  • shared platform namespace: system
  • default service account and rc.d identity: clawdie
  • assistant display name is separate and does not rename infrastructure
  • TENANT_ID is only for later additive tenants

Shared platform databases:

  • system_ops
  • system_brain
  • system_skills
  • system_git
  • system_web

Canonical runtime layout

Section titled “Canonical runtime layout”
FreeBSD host
├── host orchestrator
│   ├── setup.sh / npm run wizard
│   ├── rc.d service
│   ├── Telegram routing
│   ├── split-brain prompt enrichment
│   ├── operator controlplane at ai.<internal_base> (HTTP API port 3100)
│   └── Bastille / bastille cmd orchestration
├── git jail     <subnet>.2   shared Git Service
├── cms jail     <subnet>.3   shared Web Service
├── ai jail      <subnet>.4   Local AI Models when enabled
├── db jail      <subnet>.5   optional Data Service jail
└── worker jails high range   per-tenant execution jails

Reserved slots:

  • <subnet>.1 gateway on warden0
  • <subnet>.2 shared Git Service
  • <subnet>.3 shared Web Service
  • <subnet>.4 Local AI Models runtime (ollama or llama.cpp)
  • <subnet>.5 optional db jail
  • <subnet>.150 browser/gui

Here, <subnet> means the configured jail subnet base, usually AGENT_SUBNET_BASE / WARDEN_SUBNET_BASE. The repo registry example is 10.0.1.x, but live installs can use any private /24, for example 192.168.72.x.

The controlplane is NOT a jail — it runs on the host as part of the main agent service.

Naming

Section titled “Naming”

Use one platform-wide internal base, default home.arpa.

Shared platform surfaces:

  • ai.home.arpa — operator controlplane
  • cms.home.arpa — shared Web Service admin surface
  • git.home.arpa — shared Git Service admin surface

Tenant surfaces:

  • <tenant>.home.arpa — tenant home web app
  • <site>.<tenant>.home.arpa — tenant site

Why home.arpa:

  • reserved for internal home/private naming
  • avoids .local and mDNS ambiguity
  • keeps host /etc/hosts entries deterministic

Bastille shape

Section titled “Bastille shape”

Clawdie keeps jails thin by default. The optional db jail is the only thick exception in the current policy.

Shared service jails use the thin create pattern:

Terminal window
bastille create -B -g <subnet>.1 <jail> 15.0-RELEASE <subnet>.x/24 warden0

Examples:

Terminal window
bastille create -B -g 10.0.1.1 clawdie-git 15.0-RELEASE 10.0.1.2/24 warden0
bastille create -B -g 10.0.1.1 clawdie-cms 15.0-RELEASE 10.0.1.3/24 warden0
bastille create -T -B -g 10.0.1.1 clawdie-db 15.0-RELEASE 10.0.1.5/24 warden0

Patch/update behavior:

  • thin jails follow the Bastille release tree, not the host patchlevel directly
  • thick jails keep their copied base until explicitly rebuilt or refreshed
  • updating the host alone does not patch jail userland automatically

That is why a host can be on a newer p level than its jails if the Bastille release tree has not been refreshed yet.

Role split

Section titled “Role split”

db

Section titled “db”
  • PostgreSQL 18
  • Agent System Skills
  • User/Agent Memory
  • strapi_cms database/user

git

Section titled “git”
  • plain bare repositories first
  • Git Service today uses Forgejo as the shared git web/API implementation
  • provisioned by setup/git.ts at WARDEN_GIT_IP

cms

Section titled “cms”
  • nginx
  • Astro/Starlight static site
  • optional internal Strapi/bootstrap path, not a guaranteed live process

ai

Section titled “ai”
  • shared Local AI Models runtime when enabled
  • implementation can be ollama or llama.cpp
  • heavyweight models and GGUF assets are added later per use case

workers

Section titled “workers”
  • jailed agent execution
  • high-addressed, disposable execution surface

Operational rule

Section titled “Operational rule”

Use the live setup flow instead of manual jail bootstrapping:

Terminal window
./setup.sh
npm run wizard
just setup -- --step jails --create
just setup-db
just setup-git
just setup-cms
just setup -- --step hosts
just setup -- --step verify
just doctor          # health check
just pi-config       # view / validate runtime config
Section titled “Related docs”