clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/docs/JAIL-NETWORKING.md
Clawdie AI b0921f4fb4 Normalize domain defaults to home.arpa (Sam & Codex) 
---

Build: pass | Tests: pass — 603 passed (44 files)

---
Build: pass | Tests: pass — Tests  603 passed (603)
2026-04-04 09:47:07 +00:00

2.3 KiB
Raw Blame History

Jail Networking Strategy

This document defines the current networking model for Clawdie on FreeBSD.

Current Host Network

Typical host interfaces:

  • public uplink such as vtnet0
  • tailscale0 if Tailscale is enabled on the host
  • lo0 host loopback
  • warden0 private bridge for Bastille jails

Recommended Model

Use one private Warden subnet on the host:

  • bridge: warden0
  • subnet: 192.168.100.0/24
  • host gateway: 192.168.100.1

Reserved low service slots:

  • 192.168.100.2 controlplane
  • 192.168.100.3 db
  • 192.168.100.4 cms
  • 192.168.100.5 llama-cpp

Worker and automation ranges:

  • 192.168.100.101+ workers
  • 192.168.100.150 browser/gui profile

Internal Naming

Use:

  • AGENT_DOMAIN=home.arpa for local DNS zone (host uses <agent>.home.arpa; replace with real public domain when ready)
  • AGENT_INTERNAL_DOMAIN=<agent>.home.arpa for host/jail-local names

Do not use .local as the default internal zone. It conflicts with mDNS behavior and makes deterministic local resolution harder.

PF Baseline

Minimum useful PF example:

ext_if = "vtnet0"
warden_net = "192.168.100.0/24"

nat on $ext_if from $warden_net to any -> ($ext_if)
pass quick on warden0 inet from $warden_net to any keep state

That is enough to let VNET jails reach package mirrors, Telegram, providers, and other outbound services.

Exposure Model

Clawdie no longer assumes host nginx ownership.

The intended web-serving path is:

  • cms serves nginx internally on the jailed subnet
  • public exposure happens through PF, an existing reverse proxy, or a direct jail IP

This is the main reason the service jails keep fixed low addresses on the private Warden network.

Tailscale

Preferred order:

  1. host-only Tailscale
  2. optional subnet routing of 192.168.100.0/24
  3. only later, per-jail Tailscale if a specific jail truly needs its own identity

Do not copy host resolver assumptions blindly into VNET jails.

Validation

The host should prove:

  • warden0 exists
  • warden0 has 192.168.100.1/24
  • forwarding is enabled
  • PF loads cleanly
  • VNET jails can reach the internet

The jails should prove:

  • controlplane.clawdie.home.arpa resolves locally
  • db.clawdie.home.arpa resolves locally
  • cms.clawdie.home.arpa resolves locally

Use npm run setup -- --step hosts to write the managed hosts block for the host and existing jails.