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: 10.0.0.0/24
host gateway: 10.0.0.1

Reserved low service slots:

10.0.0.3 db
10.0.0.4 git
10.0.0.5 cms
10.0.0.6 ollama

Worker and automation ranges:

10.0.0.101+ workers
10.0.0.150 browser/gui profile

10.0.0.2 stays intentionally unused as a compatibility slot.

Internal Naming

Use:

AGENT_DOMAIN=<agent>.invalid until a real public domain exists
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 = "10.0.0.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:

host-only Tailscale
optional subnet routing of 10.0.0.0/24
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 10.0.0.1/24
forwarding is enabled
PF loads cleanly
VNET jails can reach the internet

The jails should prove:

db.clawdie.home.arpa resolves locally
git.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.

2.3 KiB Raw Blame History