Skip to content
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:

  • 10.0.0.1 gateway on warden0
  • 10.0.0.2 shared Git Service
  • 10.0.0.3 shared Web Service
  • 10.0.0.4 Local AI Models runtime (ollama or llama.cpp)
  • 10.0.0.5 optional db jail
  • 10.0.0.150 browser/gui

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”

Current persistent service jails use the proven create pattern:

Terminal window
bastille create -T -B -g 10.0.0.1 <jail> 15.0-RELEASE 10.0.0.x/24 warden0

Examples:

Terminal window
bastille create -T -B -g 10.0.0.1 clawdie-git 15.0-RELEASE 10.0.0.2/24 warden0
bastille create -T -B -g 10.0.0.1 clawdie-cms 15.0-RELEASE 10.0.0.3/24 warden0
bastille create -T -B -g 10.0.0.1 clawdie-db 15.0-RELEASE 10.0.0.5/24 warden0

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”