clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/README-CLAWDIE.md
Clawdie AI 84cc452497 docs: complete Codex's public/internal restructure alignment 
Codex restructured docs on 5 Apr (cc37d2c) into public/ and internal/
subdirectories. This commit completes the alignment work by updating all
references across skills, agents, and generated files.

Changes:

Skills Documentation:
- docs-deployment/SKILL.md: Update doc paths (docs/INSTALL.md → docs/public/install/install.md)
- docs-deployment/INTEGRATION.md: Update example paths for new structure
- agent-setup/SKILL.md: Update references
- ansible-freebsd/SKILL.md: Update references

Agents & Conventions:
- AGENTS.md: Add tmux "testing" window guideline for long-running commands
- AGENTS.md: Update doc path references (INSTALL.md → install.md lowercase)
- README-CLAWDIE.md: Update doc paths
- CROWDIN.md: Update structure references

Build System:
- setup/cms.ts: Improve frontmatter generation (skip files with existing h1)
- scripts/memory/embed-docs.py: Adjust for new structure
- docs-deployment/DOCUMENTATION-POLICY.md: Update guidelines

HTML/Web Output:
- html/: Version bumps, link fixes, manifest updated
- Reflect new public/ structure in rendered docs

Validation:
- All skills reference docs correctly
- Install/setup docs now at docs/public/install/
- Docs build and serve correctly (verified 6 Apr)
- 603 tests passing (from Codex's build)

Co-Authored-By: Codex (Agent) <codex@clawdie.si>
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

---
Build: pass | Tests: pass — Tests  603 passed (603)
2026-04-06 13:22:24 +00:00

4.4 KiB
Raw Blame History

Clawdie on FreeBSD

Native FreeBSD deployment with the Warden runtime on Bastille-managed jails.

Overview

Clawdie is a personal AI assistant for FreeBSD 15 with:

  • Telegram as the active user channel
  • PI (@mariozechner/pi-coding-agent) as the active coding runtime
  • Warden as the project name for the isolated execution layer
  • Bastille as the host-side jail manager
  • ZFS for snapshots, quotas, and rollback points

Current Proven State

Validated on 08.mar.2026 by Sam & Codex:

  • controlplane thick VNET jail on warden0
  • hostname controlplane.clawdie.local
  • IP 10.0.0.100/24
  • db thick VNET jail on warden0
  • hostname db.clawdie.local
  • IP 10.0.0.2/24
  • PostgreSQL 18.1 running inside db
  • host pf NAT for 10.0.0.0/24
  • host forwarding enabled
  • Sanoid policies active for db and controlplane

Naming Model

  • FreeBSD jail: isolation primitive
  • Bastille: jail manager
  • Warden runtime: Clawdie's isolated execution model built on top of jails

See docs/public/architecture/warden.md.

Canonical Network

  • host bridge: warden0
  • host gateway: 10.0.0.1
  • control-plane jail: controlplane
  • control-plane hostname: controlplane.clawdie.local
  • control-plane IP: 10.0.0.100
  • database jail: db
  • database hostname: db.clawdie.local
  • database IP: 10.0.0.2
  • worker range: 10.0.0.101+

Quick Start

git clone https://codeberg.org/Clawdie/Clawdie-AI.git /home/clawdie/clawdie-ai
cd /home/clawdie/clawdie-ai

pkg install node24 npm git python312 py312-uv rsync
npm install
npm install -g @mariozechner/pi-coding-agent
# If setup.sh did not launch onboarding automatically:
npm run wizard

Then:

  1. Review .env
  2. Configure Telegram bot token and provider credentials
  3. Follow the Bastille and networking docs below
  4. Run npm run build
  5. Start the service with ./run-clawdie.sh

Host Prerequisites

The current FreeBSD deployment depends on:

  • ZFS pool zroot
  • Bastille configured with bastille_zfs_enable="YES"
  • persistent host bridge warden0
  • gateway_enable="YES"
  • pf rules for Warden NAT and egress
  • dedicated Bastille resolver file instead of inherited Tailscale resolver state

Bastille and Jail Docs

Live Docs

  • https://domedog.pro/
  • https://domedog.pro/tailscale-jails-on-freebsd.html
  • https://domedog.pro/postgres-memory-plan.html
  • https://domedog.pro/reduced-ai-bootstrap-plan.html
  • https://domedog.pro/warden-network-troubleshooting.html
  • https://domedog.pro/pf.conf.txt
  • https://domedog.pro/sanoid.conf.txt

Runtime Layers

controlplane

Role:

  • main Clawdie control-plane jail
  • Telegram intake
  • scheduling
  • Warden task dispatch

Profile:

  • freebsd-jail
  • thick
  • vnet
  • persistent

db

Role:

  • PostgreSQL memory backend
  • persistent service

Profile:

  • freebsd-jail
  • thick
  • vnet
  • persistent

Future Workers

  • worker = thin, shared, ephemeral
  • networkedWorker = thin, VNET, ephemeral
  • browserVm = future Linux VM executor for browser/GUI automation

Snapshot Policy

Manual milestone snapshots:

  • human-named
  • day-first
  • month abbreviation

Examples:

  • @postgres18-ready-08.mar.2026
  • @fresh-08.mar.2026

Automatic snapshots:

  • handled by Sanoid
  • keep Sanoid's internal autosnap_... naming

Current automated Sanoid targets:

  • zroot/clawdie-runtime/jails/db
  • zroot/clawdie-runtime/jails/controlplane

Monitoring

Current operator checks:

  • npm run doctor
  • logs/clawdie.log
  • logs/clawdie.error.log
  • zfs list -t snapshot
  • sanoid --readonly --verbose --take-snapshots

Notes

  • PostgreSQL currently runs successfully inside db
  • allow.sysvipc=1 is required for PostgreSQL initdb
  • VNET jail creation must include -g 10.0.0.1
  • Bastille should use a dedicated resolver file instead of inheriting host Tailscale DNS
  • pf must include both NAT and warden0 pass rules for jailed egress

Attribution

FreeBSD Warden bring-up milestone validated on 08.mar.2026 by Sam & Codex.