clawdie-ai/docs/DEPLOYMENT-MODELS.md

# Deployment Models

Clawdie-AI supports two first-class deployment targets. Both run the same
core runtime — Bastille jails, PostgreSQL memory DB, nginx, Telegram
channel, rc.d service. The difference is how the host gets set up.

---

## Model 1: Cloud / VPS (current production)

**Use when:** You want Clawdie running on a remote server you can SSH into.

```
VPS / cloud host (FreeBSD 15)
  └── Bastille jails
        ├── db        (PostgreSQL 17 + pgvector)
        ├── cms       (Strapi CMS)
        └── controlplane (agent runtime)
```

**Setup path:**

```
git clone → npm run install-all → configure .env → service {agent} start
```

See [`docs/INSTALL.md`](./INSTALL.md) and the `ansible-freebsd` skill for
the full provisioning sequence.

**Characteristics:**
- Headless, SSH/Tailscale access
- Managed via Ansible playbooks
- ZFS snapshots via Sanoid for disaster recovery
- No desktop required

---

## Model 2: Bare-metal ISO (goal)

**Use when:** You want to plug a USB into your own hardware and have a
complete Clawdie system in one reboot — desktop included.

```
USB image
  └── bsdinstall (FreeBSD base + ZFS + bootloader)
  └── firstboot.sh (bsddialog wizard)
        ├── GPU detection → kld_list → Lumina desktop
        └── setup.sh → same jails as Model 1
  └── one reboot → running system
```

**Setup path:**

```
dd if=clawdie.iso of=/dev/daX → boot → answer wizard → done
```

See [`CLAWDIE-ISO.md`](../CLAWDIE-ISO.md) for the full build plan.
Target repo: `codeberg.org/Clawdie/clawdie-iso` (to be created).

**Characteristics:**
- Lumina desktop (FreeBSD-native, outpaddling/desktop-installer)
- 1 reboot for common hardware (GPU via pciconf, no intermediate reboot)
- Local access, no cloud dependency
- Same Clawdie-AI core as Model 1

---

## Shared core

Everything in this repository is shared between both models:

| Component | Both models |
|-----------|-------------|
| Agent runtime | `src/` |
| Jail definitions | `setup/` |
| Memory pipeline | `scripts/memory/` |
| Skills | `.agent/skills/` |
| Onboarding wizard | `setup/onboarding.ts` |
| Ansible playbooks | `infra/ansible/` |

The ISO build will live in a separate `clawdie-iso` repo and call
`npm run install-all` from `firstboot.sh` after base OS install — the
same entry point used in Model 1.

---

## Related docs

- [`docs/INSTALL.md`](./INSTALL.md) — Model 1 install orchestrator
- [`CLAWDIE-ISO.md`](../CLAWDIE-ISO.md) — Model 2 full build plan
- [`docs/BASTILLE.md`](./BASTILLE.md) — jail lifecycle (both models)
- [`docs/WARDEN.md`](./WARDEN.md) — ZFS layout (both models)