Introduce Warden runtime naming
This commit is contained in:
Clawdie
parent
9370f6623d
commit
170480cbc8
3 changed files with 79 additions and 8 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Clawdie - Personal AI Assistant on FreeBSD
|
||||
|
||||
> **Clawdie for FreeBSD 15 with native jail isolation**
|
||||
> **Clawdie for FreeBSD 15 with the Warden runtime on native jails**
|
||||
|
||||
[](https://www.freebsd.org/)
|
||||
[](https://docs.freebsd.org/en/books/handbook/jails/)
|
||||
|
|
@ -8,12 +8,13 @@
|
|||
|
||||
## Overview
|
||||
|
||||
Clawdie is a lean personal AI assistant for FreeBSD 15 with native jail isolation instead of Docker. It builds on NanoClaw's minimal design, then replaces Linux-container assumptions with FreeBSD-native runtime choices.
|
||||
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
|
||||
|
|
@ -33,6 +34,16 @@ We chose FreeBSD jails over Docker for:
|
|||
|
||||
**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](docs/WARDEN.md) for the naming model.
|
||||
|
||||
## Current Setup
|
||||
|
||||
### System Information
|
||||
|
|
@ -176,6 +187,7 @@ This installation includes the following Clawdie skills and customizations:
|
|||
|
||||
### Local Documentation
|
||||
|
||||
- [Warden Runtime](docs/WARDEN.md) - Clawdie naming for the isolated execution layer
|
||||
- [Bastille on FreeBSD 15](docs/BASTILLE.md) - Recommended Bastille config, ZFS layout, bootstrap, snapshots
|
||||
- [Jail Networking Strategy](docs/JAIL-NETWORKING.md) - Plain jail first, optional VNET and Tailscale later
|
||||
- [FreeBSD Jail Implementation](docs/FREEBSD-JAIL-IMPLEMENTATION.md) - Complete jail setup guide
|
||||
|
|
|
|||
21
docs/SPEC.md
21
docs/SPEC.md
|
|
@ -1,4 +1,4 @@
|
|||
# NanoClaw Specification
|
||||
# Clawdie Specification
|
||||
|
||||
A personal AI assistant accessible via messaging channels, with persistent memory per conversation, scheduled tasks, and integrations.
|
||||
|
||||
|
|
@ -45,10 +45,10 @@ A personal AI assistant accessible via messaging channels, with persistent memor
|
|||
│ │ spawns jail │
|
||||
│ ▼ │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ JAIL (FreeBSD) │
|
||||
│ WARDEN RUNTIME (FREEBSD JAIL) │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||||
│ │ AGENT RUNNER │ │
|
||||
│ │ WARDEN WORKER │ │
|
||||
│ │ │ │
|
||||
│ │ Working directory: /workspace/group (mounted from host) │ │
|
||||
│ │ Volume mounts: │ │
|
||||
|
|
@ -76,10 +76,19 @@ A personal AI assistant accessible via messaging channels, with persistent memor
|
|||
| Telegram Connection | Node.js (grammy) | Connect to Telegram, send/receive messages |
|
||||
| Message Storage | SQLite (better-sqlite3) | Store messages for polling |
|
||||
| Jail Runtime | FreeBSD jails | Isolated environments for agent execution |
|
||||
| Warden Runtime | Clawdie execution layer | Project-specific name for jailed agent execution |
|
||||
| Agent | `pi` / PI coding agent | Run the coding agent with tools and MCP servers |
|
||||
| Browser Automation | agent-browser + Chromium | Web interaction and screenshots |
|
||||
| Runtime | Node.js 20+ | Host process for routing and scheduling |
|
||||
|
||||
### Warden Naming
|
||||
|
||||
`Warden` is the Clawdie name for the isolated execution layer.
|
||||
|
||||
- **FreeBSD jail** remains the correct operating-system term
|
||||
- **Bastille** remains the host-side jail manager
|
||||
- **Warden runtime** refers to Clawdie's jailed execution model and worker dispatch
|
||||
|
||||
---
|
||||
|
||||
## Folder Structure
|
||||
|
|
@ -111,10 +120,10 @@ nanoclaw/
|
|||
│ ├── mount-security.ts # Mount allowlist validation for jails
|
||||
│ ├── telegram-auth.ts # Standalone Telegram token verification
|
||||
│ ├── task-scheduler.ts # Runs scheduled tasks when due
|
||||
│ └── jail-runner.ts # Spawns agents in jails
|
||||
│ └── jail-runner.ts # Spawns Warden workers in jails
|
||||
│
|
||||
├── jail/
|
||||
│ ├── agent-runner/ # Code that runs inside the jail
|
||||
│ ├── agent-runner/ # Code that runs inside the Warden jail worker
|
||||
│ │ ├── package.json
|
||||
│ │ ├── tsconfig.json
|
||||
│ │ └── src/
|
||||
|
|
@ -194,7 +203,7 @@ export const TRIGGER_PATTERN = new RegExp(`^@${ASSISTANT_NAME}\\b`, 'i');
|
|||
|
||||
**Note:** Paths must be absolute for jail mounts to work correctly.
|
||||
|
||||
### Container Configuration
|
||||
### Jail Configuration
|
||||
|
||||
Groups can have additional directories mounted via `jailConfig` in the SQLite `registered_groups` table (stored as JSON in the `jail_config` column). Example registration:
|
||||
|
||||
|
|
|
|||
50
docs/WARDEN.md
Normal file
50
docs/WARDEN.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Warden Runtime
|
||||
|
||||
`Warden` is the Clawdie name for its isolated execution layer.
|
||||
|
||||
It is not a replacement for FreeBSD jails or Bastille. It is the project-level name for how Clawdie runs agent work safely.
|
||||
|
||||
## Definition
|
||||
|
||||
- **FreeBSD jail**: the operating-system isolation primitive
|
||||
- **Bastille**: the host-side jail manager
|
||||
- **Warden runtime**: Clawdie's isolated agent execution layer built on top of jails
|
||||
|
||||
In practice:
|
||||
|
||||
- Bastille creates and manages the jails
|
||||
- FreeBSD enforces the isolation
|
||||
- Clawdie dispatches agent work into the Warden runtime
|
||||
|
||||
## Why Use the Name
|
||||
|
||||
`Warden` gives the runtime a project-specific identity without hiding the underlying tooling.
|
||||
|
||||
That keeps operations clear:
|
||||
|
||||
- use standard Bastille docs and commands when managing jails
|
||||
- use `Warden` when describing Clawdie's execution model
|
||||
|
||||
## Recommended Usage
|
||||
|
||||
Use `Warden` in:
|
||||
|
||||
- architecture docs
|
||||
- operator language
|
||||
- future helper scripts and wrapper commands
|
||||
- future jail names such as `warden-worker` or `warden-browser`
|
||||
|
||||
Do not use `Warden` to rename:
|
||||
|
||||
- `bastille.conf` keys
|
||||
- Bastille's default path layout
|
||||
- FreeBSD jail terminology itself
|
||||
|
||||
## Long-Term Direction
|
||||
|
||||
The intended model is:
|
||||
|
||||
- **Warden jail runtime** for PI, coding, CLI work, and low-overhead task execution
|
||||
- optional **Warden browser VM** later via `bhyve` for Linux desktop and browser automation workloads
|
||||
|
||||
That keeps the lightweight path lightweight while still leaving room for a heavier GUI executor later.
|
||||
Loading…
Add table
Reference in a new issue