clawdie/clawdie-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-ai/docs/JAIL-NETWORKING.md
Clawdie 9370f6623d Add Bastille and jail networking docs
2026-03-08 09:18:35 +01:00

2.6 KiB
Raw Blame History

Jail Networking Strategy

This document describes the recommended networking path for Clawdie on FreeBSD.

Current Host Network

The current host layout is:

  • vtnet0: public internet
  • tailscale0: host Tailscale interface
  • lo0: host loopback

That is already enough for the first Clawdie jail milestone.

Recommendation

Use the simplest possible networking model first.

Phase 1: Plain Jail

  • one native FreeBSD jail
  • outbound internet access only
  • PI runs inside the jail
  • Clawdie can invoke the jail worker

This is the first thing to prove.

Phase 2: Optional VNET

Add VNET only when you need a separate network stack per jail.

That usually means:

  • a dedicated bridge
  • a private jail subnet
  • host-side forwarding/NAT
  • Bastille VNET templates

Phase 3: Optional Tailscale Reachability

There are three ways to expose jail workloads to Tailscale later.

  1. Host-only Tailscale
  • simplest
  • host has the tailnet identity
  • jails remain internal
  1. Subnet-routed jail network
  • recommended next step
  • host advertises the jail subnet to Tailscale
  • jails are reachable through the host
  1. Tailscale inside each jail
  • highest complexity
  • each jail becomes its own tailnet node
  • only worth it when per-jail identity matters

Recommended Future Naming

If you later enable VNET networking, use project-specific naming:

  • loopback: clawdie0
  • pf table: clawdie_jails
  • bridge: clawbr0
  • jail subnet: 10.83.0.0/24
  • host gateway on that subnet: 10.83.0.1

These names keep FreeBSD and Bastille defaults understandable while making project-owned objects obvious.

Why Not Start With VNET

Starting with VNET adds several moving parts at once:

  • bridge creation
  • address planning
  • pf NAT rules
  • jail interface wiring
  • Tailscale interaction

That is too much for the first runtime proof.

For Clawdie, the order should be:

  1. host runtime works
  2. plain jail works
  3. PI works inside the jail
  4. Clawdie can execute one jailed turn
  5. only then consider VNET

Why Not Start With Tailscale Inside the Jail

Tailscale inside every jail is useful, but it solves a more advanced problem:

  • per-jail reachability
  • per-jail identity
  • mesh exposure of internal services

Clawdie's first runtime requirement is much simpler:

  • Telegram access
  • provider API access
  • jailed execution

Those do not require per-jail Tailscale.

Future Browser/GUI Workloads

If you later want a full Linux desktop for browser automation, treat that as a separate executor.

Use:

  • FreeBSD jail for PI/coding/CLI work
  • bhyve Linux VM for GUI/browser tasks

Do not force the browser/desktop use case into the plain jail runtime path.