How It Works
Architecture, components, and quick reference
Everything we use to run Clawdie — documented openly. FreeBSD, nginx, Tailscale, Stripe — if it runs on our server, it can run on yours.
Architecture
Clawdie runs on a two-server split architecture connected via Tailscale VPN.
domedog — Brain
Agent runtime, Telegram integration, Supabase memory, Playwright browser orchestration, tmux glass-pane console.
Control plane · FreeBSD 15clawd — Eyes
Real Chrome browser on Xfce4 desktop, Chrome DevTools Protocol at port 9223, VNC monitoring at port 5901.
Browser server · CDPClawdie is moving toward a split-brain model: Brain A is prebuilt local knowledge imported into the database jail during bootstrap. Brain B is dynamic user and agent memory that evolves later.
Headless environments fail against Cloudflare Turnstile challenges. Running Chrome on a dedicated desktop server maintains human-like browser behavior while the operator monitors via VNC.
Quick reference
| Component | Technology | Purpose |
|---|---|---|
| OS | FreeBSD 15 | Server platform |
| Runtime | Node.js 24+ | Agent orchestration |
| Language | TypeScript | Type-safe codebase |
| Isolation | FreeBSD Jails | Agent sandboxing |
| Web server | nginx | Reverse proxy, static sites |
| SSL | Let's Encrypt | HTTPS certificates |
| VPN | Tailscale | Encrypted mesh network |
| Firewall | PF | Packet filtering |
| Chat | Telegram | Operator interface |
| Memory | Postgres / pgvector | Persistent storage |
| Browser | Playwright + CDP | Web automation |
| Payments | Stripe | Billing integration |
| ProtonMail SMTP | Outbound email from custom domain | |
| License | BSD-3-Clause | Same license as FreeBSD |
Setup guides
Step-by-step guides for deploying and operating a self-hosted AI assistant on FreeBSD.
Split Brain
Brain A and Brain B explained in plain language and in technical terms: built-in local knowledge first, user memory later.
Brain A · Brain B · Local knowledgeInstallation Guide
Setup wizard walkthrough, jail provisioning, IP scheme, and first test install screenshots.
Wizard · Bastille · 11 stepsFreeBSD Setup
FreeBSD 15 deployment, jail configuration, PF firewall, and Clawdie-specific system setup.
FreeBSD 15 · Jails · PF firewallNginx + SSL
Web server configuration, virtual hosts, HTTPS with Let's Encrypt, and security hardening.
nginx · Let's Encrypt · TLS 1.3Tailscale VPN
Mesh networking between servers, SSH over Tailscale, and firewall integration on FreeBSD.
Tailscale · WireGuard · Mesh VPNStripe Agents
AI agent integration with Stripe APIs — payments, billing, and customer management via function calling.
Stripe · AI Agents · PaymentsProtonMail
Send emails from your custom domain address via ProtonMail SMTP tokens. No daemon required.
ProtonMail · Email · SMTPNanoClaw Upstream
Track improvements from the upstream NanoClaw project. Fetch-only — the operator decides what to apply.
NanoClaw · Upstream · Git remoteProject
Release history, license reasoning, and project meta.
Changelog
Tagged releases with annotated commit history. Regenerated from git tags on each release.
Releases · Git tags · HistoryLicense — BSD-3-Clause
Why we chose FreeBSD's license over MIT. The non-endorsement clause, PlayStation and Apple context, NanoClaw compatibility.
BSD-3 · FreeBSD · NanoClaw