Skip to content
Clawdie

Jail Networking Strategy

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

Current Host Network

Section titled “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
Section titled “Recommended Model”

Use one private Warden subnet on the host:

  • bridge: warden0
  • subnet: operator-configurable (AGENT_SUBNET_BASE / registry)
  • host gateway: <subnet>.1

Reserved low service slots:

  • <subnet>.2 git
  • <subnet>.3 cms
  • <subnet>.4 Local AI Models
  • <subnet>.5 optional db

Worker and automation ranges:

  • <subnet>.101+ workers
  • <subnet>.150 browser/gui profile

Internal Naming

Section titled “Internal Naming”

Use:

  • PLATFORM_INTERNAL_BASE=home.arpa by default
  • ai.home.arpa for the operator controlplane
  • cms.home.arpa and git.home.arpa for shared admin surfaces
  • <tenant>.home.arpa for tenant homes
  • <site>.<tenant>.home.arpa for tenant sites

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

PF Baseline

Section titled “PF Baseline”

Minimum useful PF example:

ext_if = "vtnet0"
warden_net = "<subnet>.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

Section titled “Exposure Model”

Clawdie no longer assumes host nginx ownership of every public surface.

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
  • docs.clawdie.si can be fronted by host nginx or another edge proxy and forwarded to the cms jail

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

Tailscale

Section titled “Tailscale”

Preferred order:

  1. host-only Tailscale
  2. optional subnet routing of your chosen Warden subnet (for example 192.168.72.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

Section titled “Validation”

The host should prove:

  • warden0 exists
  • warden0 has <subnet>.1/24
  • forwarding is enabled
  • PF loads cleanly
  • VNET jails can reach the internet

The host and jails should prove:

  • ai.home.arpa resolves locally
  • cms.home.arpa resolves locally
  • git.home.arpa resolves locally
  • tenant homes and sites such as mevy.home.arpa and blog.mevy.home.arpa resolve locally when enabled

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