# 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.03.2026` by Sam & Codex:

- `controlplane` thick VNET jail on `warden0`
- hostname `ai.clawdie.si`
- IP `192.168.100.100/24`
- `db` thick VNET jail on `warden0`
- hostname `db.clawdie.si`
- IP `192.168.100.2/24`
- PostgreSQL `18.1` running inside `db`
- host `pf` NAT for `192.168.100.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/WARDEN.md](docs/WARDEN.md).

## Canonical Network

- host bridge: `warden0`
- host gateway: `192.168.100.1`
- control-plane jail: `controlplane`
- control-plane hostname: `ai.clawdie.si`
- control-plane IP: `192.168.100.100`
- database jail: `db`
- database hostname: `db.clawdie.si`
- database IP: `192.168.100.2`
- worker range: `192.168.100.101+`

## Quick Start

```bash
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
npm install
npm install -g @mariozechner/pi-coding-agent
cp .env.example .env
```

Then:

1. Fill in `.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 `./start-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

- [docs/BASTILLE.md](docs/BASTILLE.md)
- [docs/JAIL-NETWORKING.md](docs/JAIL-NETWORKING.md)
- [docs/FREEBSD-JAIL-IMPLEMENTATION.md](docs/FREEBSD-JAIL-IMPLEMENTATION.md)
- [docs/POSTGRES-MEMORY.md](docs/POSTGRES-MEMORY.md)
- [docs/MONITORING.md](docs/MONITORING.md)

## 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 192.168.100.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.03.2026` by Sam & Codex.
