clawdie-ai/README-CLAWDIE.md

Clawdie - Personal AI Assistant on FreeBSD

Clawdie for FreeBSD 15 with the Warden runtime on native jails

Overview

Clawdie is a lean personal AI assistant for FreeBSD 15 with the Warden runtime on native FreeBSD jails instead of Docker. It builds on NanoClaw's minimal design, then replaces Linux-container assumptions with FreeBSD-native runtime choices.

Key Features:

• 🏠 Native FreeBSD - No Linux emulation, no Docker overhead
• 🔒 Jail Isolation - Secure OS-level containers with ZFS snapshots
• 🛡️ Warden Runtime - Clawdie's isolated execution layer on top of FreeBSD jails
• ⚡ Better Performance - Single layer: FreeBSD → Jail → Node.js
• 💾 ZFS Integration - Snapshots, quotas, compression
• 📊 Online Documentation - Live docs at domedog.pro

Architecture Decision: Jails vs Docker

We chose FreeBSD jails over Docker for:

Aspect	Docker on FreeBSD	FreeBSD Jails
Performance	Good (emulation overhead)	Excellent (native)
Layers	FreeBSD → Linux → Docker	FreeBSD → Jail
Security	Good	Excellent
Networking	Docker bridge	Native IP
Complexity	High	Low
ZFS Integration	Manual	Native

Result: Simpler, faster, more secure.

Warden Runtime

Clawdie uses Warden as the project name for its isolated execution layer.

• FreeBSD jail: the native isolation primitive
• Bastille: the host-side jail manager
• Warden runtime: Clawdie's jailed agent execution model

See Warden Runtime for the naming model.

Current Setup

System Information

Component	Value
OS	FreeBSD 15.0-RELEASE
Hostname	osa
Architecture	amd64 (x86_64)
Runtime	FreeBSD Jail (native)
Node.js	v24+ (via pkg or nvm)
Python	3.12.12 + uv package manager
Filesystem	ZFS
User	clawdie

ZFS Layout

NAME                       USED  AVAIL  REFER  MOUNTPOINT
zroot                     6.01G  89.4G   424K  none
zroot/ROOT                5.83G  89.4G   424K  none
zroot/ROOT/default        5.83G  89.4G  4.90G  /
zroot/home                 152M  89.4G   156K  /home
zroot/home/clawdie         152M  89.4G   152M  /home/clawdie
zroot/tmp                 3.07M  89.4G  3.07M  /tmp
zroot/var                 11.8M  89.4G   424K  /var

Jail Configuration (Planned)

Jail: clawdie
├── Hostname: ai.clawdie.si
├── IP: 192.168.1.xxx
├── Path: /jails/clawdie
├── Mounts:
│   ├── /home/clawdie/clawdie-cp (ro)
│   └── /home/clawdie/.config/clawdie-cp (rw)
└── Resources:
    ├── Memory: 2G max
    ├── CPU: 2 cores
    └── Processes: 1000 max

Installation

Prerequisites

• FreeBSD 15.0-RELEASE
• ZFS root installation
• Root access or sudo
• Domain: clawdie.si (registered 28.02.2026)

Quick Start

# 1. Clone your fork
git clone https://codeberg.org/Clawdie/Clawdie-AI.git /home/clawdie/clawdie-cp
cd /home/clawdie/clawdie-cp

# 2. Install dependencies
pkg install node24 npm git python312 py312-uv

# 3. Install project dependencies
npm install

# 4. Install the default PI TUI engine
npm install -g @mariozechner/pi-coding-agent

# 5. Copy environment template
cp .env.example .env

# 6. Add your provider key to .env (default: OPENROUTER_API_KEY)

# 7. Setup
npm run setup

Jail Setup (Recommended)

See these docs for the current host-side jail plan:

• Bastille on FreeBSD 15
• Jail Networking Strategy
• FreeBSD Jail Implementation

Quick jail setup:

# Create ZFS datasets for jail
sudo zfs create -o mountpoint=/jails zroot/jails
sudo zfs create zroot/jails/clawdie
sudo zfs create zroot/jails/clawdie/home

# Create jail configuration
sudo vi /etc/jail.conf.d/clawdie.conf

# Start jail
sudo service jail start clawdie

# Install Node.js inside jail
sudo pkg -j clawdie install node20 npm git

Applied Skills

This installation includes the following Clawdie skills and customizations:

Skill	Description
/add-telegram	Telegram channel support
/add-voice-transcription	Whisper voice note transcription
/add-gmail	Gmail integration
/add-slack	Slack channel support
/add-discord	Discord channel support
/add-telegram-swarm	Agent swarm teams in Telegram
/x-integration	X (Twitter) posting/replying
/qodo-pr-resolver	AI-powered PR review
/get-qodo-rules	Load coding rules from Qodo

Configuration Differences From Upstream

Setting	NanoClaw Default	Clawdie Custom
Main channel	WhatsApp	Telegram
Date format	en-US locale	de-DE locale (European)
Memory	Local files	Supabase (planned)
Identity	None	SOUL.md + IDENTITY.md
Operator console	Logs only	tmux glass-pane
Runtime	Docker	FreeBSD Jail

Documentation

Live Documentation

• Clawdie PRD: https://domedog.pro/
• FreeBSD Setup: https://domedog.pro/nanoclaw-on-freebsd.html
• Nginx Setup: https://domedog.pro/clawdie-and-nginx.html
• Stripe Integration: https://domedog.pro/stripe-agents-plan.html
• OpenClaw Transition: https://domedog.pro/clawdie-openclaw-transition-plan.html

Local Documentation

• Warden Runtime - Clawdie naming for the isolated execution layer
• Bastille on FreeBSD 15 - Recommended Bastille config, ZFS layout, bootstrap, snapshots
• Jail Networking Strategy - Plain jail first, optional VNET and Tailscale later
• FreeBSD Jail Implementation - Complete jail setup guide
• NanoClaw → Clawdie Version History - Upstream lineage and version tracking
• Architecture - Technical architecture
• Security - Security model
• Requirements - Design requirements

Testing

Jail Validation Tests

We have comprehensive tests to ensure the FreeBSD jail runtime behaves as expected:

# Run jail validation tests
npm test src/freebsd-jail.test.ts

# Run jail runtime tests
npm test src/jail-runtime.test.ts

# Run jail configuration tests
npm test src/jail-config.test.ts

# Run all tests
npm test

What Tests Validate

• ✅ Linux emulation is disabled
• ✅ Running inside a jail
• ✅ Jail configuration exists
• ✅ Native FreeBSD syscalls (no emulation)
• ✅ Proper jail security isolation
• ✅ Resource limits configured

Development

File Structure

/home/clawdie/clawdie-cp/
├── src/
│   ├── jail-runtime.ts          # Jail detection and management
│   ├── jail-runtime.test.ts     # Jail runtime tests
│   ├── jail-config.ts           # Jail configuration generation
│   ├── jail-config.test.ts      # Jail config tests
│   ├── freebsd-jail.test.ts     # Comprehensive jail validation
│   ├── index.ts                 # Main entry point
│   └── ...
├── docs/
│   ├── FREEBSD-JAIL-IMPLEMENTATION.md  # Jail setup guide
│   ├── NANOCLAW-TO-CLAWDIE.md          # Version tracking
│   └── ...
├── .agent/skills/               # Applied skills
├── skills-engine/                # Skills management
└── package.json

Key Files Modified From Upstream

File	Change
src/index.ts	Channel routing for Telegram, Gmail, Slack, Discord
src/config.ts	Channel configurations
jail/agent-runner/src/index.ts	Voice transcription, Gmail tools
AGENTS.md	European date format, custom rules

Added Files (Not in Upstream)

src/channels/telegram.ts
src/channels/gmail.ts
src/channels/slack.ts
src/channels/discord.ts
src/jail-runtime.ts
src/jail-config.ts
src/freebsd-jail.test.ts
skills-engine/
.agent/skills/add-telegram/
.agent/skills/add-gmail/
.agent/skills/add-slack/
.agent/skills/add-discord/
.agent/skills/add-telegram-swarm/
.agent/skills/add-voice-transcription/
.agent/skills/x-integration/
.agent/skills/qodo-pr-resolver/
.agent/skills/get-qodo-rules/

Version Tracking

State is tracked in .nanoclaw/state.json:

{
  "version": "1.0.0",
  "base_commit": "abc123...",
  "applied_skills": [
    {
      "name": "add-telegram",
      "applied_at": "2026-02-28T10:00:00Z",
      "file_hashes": { ... }
    }
  ]
}

Current Version: v0.6 (06.03.2026)

Update Process

To pull upstream NanoClaw changes while preserving Clawdie customizations:

# Add upstream remote (one-time)
git remote add upstream https://github.com/openclaw/nanoclaw

# Check for updates
npm run update:preview

# Apply updates (skills engine handles merge)
npm run update

The skills engine automatically rebases your customizations onto the new base.

Security

Jail Security Features

• Devfs Ruleset 4 - Basic devices only (null, zero, random)
• No host filesystem access - Isolated from /home/clawdie on host
• Network isolation - Own IP, no access to host network stack
• Resource limits - Memory, CPU, and process limits
• ZFS quotas - Disk space limits per jail

Attack Surface Reduction

Surface	Upstream NanoClaw	Clawdie on FreeBSD
Runtime	Docker daemon	None (native jails)
Emulation layer	Linux compat	None
Extensions	34+	10 (curated)
Channels	13+ available	4 (Telegram, Gmail, Slack, Discord)

See SECURITY.md for full security model.

Future Plans

Git Hosting

• Current: codeberg.org/Clawdie/Clawdie-AI
• Planned: git.clawdie.si (self-hosted)
• Strategy: Mirror to both locations

Roadmap

MVP (Current - v0.6)

• FreeBSD 15 setup
• ZFS configuration
• Jail implementation design
• Tests for jail validation
• Jail creation and deployment
• Telegram working
• tmux glass-pane working

v0.7 (Next)

• Self-hosted git.clawdie.si
• clawdie.si landing page
• Supabase memory integration
• Jail snapshots and backup strategy

v1.0

• 2+ weeks stable operation
• Browser automation (Playwright in jail)
• Memory system reliable
• Security audit

Links

• Clawdie PRD: https://domedog.pro/
• NanoClaw Upstream: https://github.com/openclaw/nanoclaw
• Clawdie Domain: https://clawdie.si
• Discord: https://discord.gg/VDdww8qS42
• Codeberg: https://codeberg.org/Clawdie/Clawdie-AI

Contributing

This is the active Clawdie project for FreeBSD. For upstream contributions:

• NanoClaw: https://github.com/openclaw/nanoclaw
• OpenClaw: https://github.com/openclaw/openclaw

For Clawdie-specific issues, use Codeberg issues.

License

Same as upstream NanoClaw (check LICENSE file).

---

Clawdie · clawdie.si · built on NanoClaw

Last updated: 06.03.2026 - v0.6