# 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

## Default Warden Profiles

Warden uses distinct jail profiles so the control-plane and worker layers do not collapse into one shape.

| Profile | Runtime | Role | Provisioning | Networking | Persistent | Use |
| ------- | ------- | ---- | ------------ | ---------- | ---------- | --- |
| `controlPlane` | `freebsd-jail` | `control-plane` | `thick` | `vnet` | yes | Main Clawdie control-plane jail on `warden0` |
| `worker` | `freebsd-jail` | `worker` | `thin` | `shared` | no | Default short-lived worker jail |
| `networkedWorker` | `freebsd-jail` | `networked-worker` | `thin` | `vnet` | no | Future worker needing its own network stack |
| `browserVm` | `linux-vm` | `browser-vm` | `image` | `vm-bridged` | yes | Future Linux desktop/browser executor |

This policy is now encoded in `src/jail-config.ts`.

## 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
- **Warden browser VM** later via `bhyve` for Linux desktop and browser automation workloads

The browser VM is intentionally not modeled as a jail option. It is a separate runtime class.

## Browser VM Profiles

The future Linux VM executor is split into image profiles so operators do not need
to choose between one bloated template and repeated one-off builds.

Canonical profiles:

- `base-tmux`: Debian Trixie 13 minimal, terminal-only, canonical clone source
- `browser`: minimal graphical/browser automation profile without a full desktop shell
- `xfce`: lightweight desktop profile and default GUI option
- `i3`: lightweight tiling desktop profile
- `kde`: fuller desktop profile

Canonical starting resources:

- RAM: `4G`
- disk: `30G`
- CPU: `2 vCPU`

The intended base image flow is:

1. create `base-tmux`
2. snapshot it
3. derive `browser`, `xfce`, `i3`, and `kde` from that known source

Rollback classes for browser workloads:

- `personal-workspace`: persistent human-used desktop, milestone rollback only
- `automation-base`: stable source image, milestone rollback only
- `automation-runner`: disposable clone, reset or destroy after each run

## Canonical Control-Plane Network

The current control-plane defaults are:

- jail name: `controlplane`
- hostname: `ai.clawdie.si`
- bridge: `warden0`
- subnet: `192.168.100.0/24`
- host gateway: `192.168.100.1`
- control-plane IP: `192.168.100.100`
- worker range: `192.168.100.101+`
