<p align="center">
  <h1 align="center">🦞 Clawdie</h1>
</p>

<p align="center">
  <strong>Personal AI Assistant on FreeBSD</strong>
</p>

<p align="center">
  A lean, secure AI assistant running on FreeBSD 15 with native jail isolation.
</p>

<p align="center">
  <a href="https://ai.clawdie.si">Documentation</a>&nbsp; • &nbsp;
  <a href="https://domedog.pro">PRD</a>&nbsp; • &nbsp;
  <a href="https://clawdie.si">Website</a>&nbsp; • &nbsp;
  <a href="https://codeberg.org/Clawdie/Clawdie-AI">Codeberg</a>&nbsp; • &nbsp;
  <a href="https://discord.gg/VDdww8qS42">Discord</a>
</p>

---

## Overview

Clawdie is a personal AI assistant for FreeBSD 15 with native jail isolation instead of Docker. It runs AI agents securely in FreeBSD jails with ZFS integration, providing better performance and simpler architecture than container emulation.

**Key Features:**

- 🏠 **Native FreeBSD** - No Linux emulation, native jail isolation
- 🔒 **Jail Isolation** - Secure OS-level containers with ZFS snapshots
- ⚡ **Better Performance** - Single layer: FreeBSD → Jail → Node.js
- 💾 **ZFS Integration** - Snapshots, quotas, compression
- 🤖 **Robot OS Ready** - clawdie-robot for CNC control (in development)
- 📊 **Online Documentation** - Live docs at [ai.clawdie.si](https://ai.clawdie.si)

## Why Clawdie?

### Why Jails Instead of Docker?

| 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.

### Why Clawdie?

[NanoClaw](https://github.com/openclaw/nanoclaw) provides the upstream foundation: a minimal, secure AI assistant that runs agents in isolated containers. Clawdie extends that work for FreeBSD users who want:

- Native performance without Linux emulation
- ZFS integration for snapshots and quotas
- Simpler architecture (fewer layers)
- Robot OS integration for CNC manufacturing

## Architecture

```
User Channels (Telegram, Gmail, Slack, Discord)
  ↓
SQLite Database
  ↓
Polling Loop (Node.js)
  ↓
FreeBSD Jail (Isolated Agent)
  ↓
Response
```

**Single Node.js process.** Agents execute in isolated FreeBSD jails with filesystem isolation via nullfs mounts. Only mounted directories are accessible. Per-group message queue with concurrency control. IPC via filesystem.

### Key Files

- `src/index.ts` - Orchestrator: state, message loop, agent invocation
- `src/channels/*.ts` - Channel connections (Telegram, Gmail, Slack, Discord)
- `src/ipc.ts` - IPC watcher and task processing
- `src/router.ts` - Message formatting and outbound routing
- `src/group-queue.ts` - Per-group queue with global concurrency limit
- `src/jail-runner.ts` - Spawns jailed agent processes and streams output
- `src/jail-runtime.ts` - FreeBSD jail detection and management
- `src/jail-config.ts` - Jail configuration generation
- `src/task-scheduler.ts` - Runs scheduled tasks
- `src/db.ts` - SQLite operations (messages, groups, sessions, state)
- `groups/*/AGENTS.md` - Per-group memory

## What It Supports

- **Messenger I/O** - Message Clawdie from your phone. Supports Telegram, Gmail, Slack, Discord, and headless operation.
- **Isolated group context** - Each group has its own `AGENTS.md` memory, isolated filesystem, and runs in its own jail sandbox with only that filesystem mounted.
- **Main channel** - Your private channel (self-chat) for admin control; every group is completely isolated.
- **Scheduled tasks** - Recurring jobs that run the AI agent and can message you back.
- **Web access** - Search and fetch content from the Web.
- **Jail isolation** - Agents are sandboxed in FreeBSD jails with ZFS snapshots.
- **Agent Swarms** - Spin up teams of specialized agents that collaborate on complex tasks.
- **Optional integrations** - Add Gmail, Slack, Discord, Telegram via skills.

## Installation

### Prerequisites

- FreeBSD 15.0-RELEASE
- ZFS root installation
- Root access or sudo
- Node.js 24+
- Python 3.12+

### Quick Start

```bash
# 1. Clone the repository
git clone https://codeberg.org/Clawdie/Clawdie-AI.git /home/clawdie/clawdie-ai
cd /home/clawdie/clawdie-ai

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

# 3. Install Node.js 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. Run setup
npm run setup
```

The setup process will guide you through:

- Environment configuration
- PI TUI runtime configuration (`pi`, default provider, model)
- Channel authentication (Telegram, etc.)
- Jail creation (optional, can run without jails initially)
- Service configuration

## FreeBSD Milestone

<p align="center">
  <img src="docs/tmux-screenshot-sample.png" alt="tmux diagnostic screenshot captured by Clawdie" width="720">
  <br>
  <em>Diagnostic screenshot captured by tmux-screenshot skill — auto-detects failure and success signatures</em>
</p>

Validated on `08.03.2026` by Sam & Codex:

- `controlplane` thick VNET jail on `warden0`
- `ai.clawdie.si` on `192.168.100.100`
- `db` thick VNET jail on `warden0`
- `db.clawdie.si` on `192.168.100.2`
- PostgreSQL `18.1` running inside `db`
- Warden NAT and resolver baseline working on the host
- Sanoid policies active for `db` and `controlplane`

Operational docs for this milestone:

- [Bastille on FreeBSD 15](docs/BASTILLE.md)
- [Jail Networking Strategy](docs/JAIL-NETWORKING.md)
- [PostgreSQL Memory Plan](docs/POSTGRES-MEMORY.md)
- [Monitoring Model](docs/MONITORING.md)

## Usage

Talk to your assistant with the trigger word (default: `@Clawdie`):

```
@Clawdie send an overview of the sales pipeline every weekday morning at 9am
@Clawdie review the git history for the past week each Friday and update the README
@Clawdie every Monday at 8am, compile news on AI developments and message me a briefing
```

Run `npm run doctor` to check system health (runtime, jails, networking, services).

From the main channel (your self-chat), you can manage groups and tasks:

```
@Clawdie list all scheduled tasks across groups
@Clawdie pause the Monday briefing task
@Clawdie join the Family Chat group
```

## Customizing

Clawdie doesn't use configuration files. To make changes, just tell the AI agent what you want:

- "Change the trigger word to @Assistant"
- "Remember in the future to make responses shorter and more direct"
- "Add a custom greeting when I say good morning"
- "Store conversation summaries weekly"

Or run `/customize` for guided changes.

The codebase is small enough that the AI agent can safely modify it.

## Philosophy

**Small enough to understand.** One process, a few source files, no microservices. If you want to understand the full Clawdie codebase, ask the AI agent to walk you through it.

**Secure by isolation.** Agents run in FreeBSD jails with filesystem isolation via nullfs mounts. They can only access explicitly mounted directories. Bash access is safe because commands run inside the jail, not on your host.

**Built for the individual user.** Clawdie isn't a monolithic framework; it's software that fits each user's exact needs. You make your own fork and have the AI agent modify it to match your requirements.

**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.

**AI-native.**

- No installation wizard; the AI agent guides setup.
- No monitoring dashboard; ask the AI what's happening.
- No debugging tools; describe the problem and the AI fixes it.

**Skills over features.** Instead of adding features (e.g., support for Telegram) to the codebase, contributors submit skills like `/add-telegram` that transform your fork. You end up with clean code that does exactly what you need.

## Clawdie Ecosystem

| Component         | Description                  | Status      |
| ----------------- | ---------------------------- | ----------- |
| **controlplane**  | Bastille jail ID for the control plane | Production  |
| **clawdie-robot** | Robot OS for CNC control     | Development |
| **clawdie-vm**    | Browser automation (bhyve)   | Planned     |
| **ai.clawdie.si** | Documentation site           | Live        |
| **domedog.pro**   | Product requirements         | Live        |

### Robot OS (clawdie-robot)

Clawdie-robot is the **operating system of the CNC robot** — an open source machine designed to manufacture geodesic dome components. It translates dome designs from [OSA](https://osa.smilepowered.org) into G-code, manages the build sequence, and logs everything to persistent memory.

See `clawdie-robot/README.md` for details.

## Contributing

**Don't add features. Add skills.**

If you want to add Slack support, don't create a PR that adds Slack alongside Telegram. Instead, contribute a skill file (`.agent/skills/add-slack/SKILL.md`) that teaches the AI agent how to transform a Clawdie installation to use Slack.

Users then run `/add-slack` on their fork and get clean code that does exactly what they need, not a bloated system trying to support every use case.

### Available Skills (31)

**Channels:** add-telegram, add-discord, add-gmail, add-slack, add-voice-transcription, x-integration

**Jail & Infrastructure:** warden-bootstrap, warden-pf, warden-zfs, warden-health, bastille-network, browser-vm, freebsd-admin, sanoid

**Operations:** nginx, nginx-glasspane, telegram-admin, tmux-screenshot, postgres-memory

**Frontend & CMS:** astro, strapi

**Agent:** coding-agent, add-telegram-swarm, add-parallel

**Utility:** setup, update, customize, debug, get-qodo-rules, qodo-pr-resolver

### Skills Structure

```
.agent/skills/add-telegram/
├── SKILL.md           # Skill documentation and instructions
├── manifest.yaml      # Skill metadata
├── add/               # Files to add
│   └── src/channels/telegram.ts
├── modify/            # Files to modify
│   └── src/config.ts
└── tests/             # Skill tests
    └── telegram.test.ts
```

## Requirements

- FreeBSD 15.0-RELEASE
- Node.js 24+
- Python 3.12+ (for voice transcription and other features)
- ZFS (recommended)
- Optional: Telegram bot token, Gmail credentials, etc.

## Security

Agents run in FreeBSD jails with filesystem isolation, not behind application-level permission checks. They can only access explicitly mounted directories. The codebase is small enough that you can review it. See [docs/SECURITY.md](docs/SECURITY.md) for the full security model.

## Documentation

- **[ai.clawdie.si](https://ai.clawdie.si)** - Complete documentation
- **[domedog.pro](https://domedog.pro)** - Product requirements document
- **[docs/FREEBSD-JAIL-IMPLEMENTATION.md](docs/FREEBSD-JAIL-IMPLEMENTATION.md)** - Jail implementation details
- **[AGENTS.md](AGENTS.md)** - Agent development guidelines

## Community

Questions? Ideas? [Join the Discord](https://discord.gg/VDdww8qS42).

## Acknowledgments

Clawdie is a fork of [NanoClaw](https://github.com/openclaw/nanoclaw) by [Gavriel](https://github.com/openclaw), built on the [OpenClaw](https://github.com/openclaw/openclaw) ecosystem created by [Peter Steinberger](https://github.com/steipete).

NanoClaw's philosophy of minimalism, security through isolation, and AI-native design made this fork possible. We extend it with FreeBSD-specific optimizations and Robot OS integration.

## License

BSD 3-Clause License

Copyright (c) 2026, Sam (Samo Blatnik)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

See [LICENSE](LICENSE) for full text.

---

<p align="center">
  <strong>Clawdie</strong> · Personal AI Assistant on FreeBSD<br>
  <a href="https://clawdie.si">clawdie.si</a> · <a href="https://ai.clawdie.si">ai.clawdie.si</a><br>
  <em>Built on NanoClaw · Optimized for FreeBSD</em>
</p>
