# 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

2. Subnet-routed jail network
- recommended next step
- host advertises the jail subnet to Tailscale
- jails are reachable through the host

3. 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.