😈 Clawdie on FreeBSD 15 exploration

1. The Challenge

Clawdie uses Docker containers to isolate agent execution. Each agent runs in a Linux container with:

• Node.js 22 runtime
• Chromium for browser automation
• @anthropic-ai/claude-code CLI
• Isolated filesystem and IPC

FreeBSD doesn't have native Docker. But we have bhyve — the BSD hypervisor. Can we make it work?

2. Architecture Options

Option A: Full Linux VM

Run the entire Clawdie stack inside a Debian/Ubuntu bhyve VM.

Option B: Hybrid (FreeBSD Host + Docker VM) recommended

Node.js runs natively on FreeBSD. Only Docker runs in a minimal Linux VM.

┌─────────────────────────────────────────────────────────────────┐
│  FreeBSD 15 Host                                                │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Node.js (Native)                                         │  │
│  │  ├── Clawdie main process                                │  │
│  │  ├── Telegram/WhatsApp channel                            │  │
│  │  ├── Message routing & IPC                                │  │
│  │  ├── SQLite database                                      │  │
│  │  └── tmux glass-pane                                      │  │
│  └─────────────────────┬─────────────────────────────────────┘  │
│                        │                                        │
│                        │ DOCKER_HOST=tcp://10.0.0.2:2375        │
│                        ▼                                        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  bhyve Linux VM (Alpine or Debian minimal)               │  │
│  │  ├── Docker daemon only                                   │  │
│  │  ├── nanoclaw-agent images                                │  │
│  │  ├── ~512MB RAM, 1 vCPU                                   │  │
│  │  └── No SSH, no GUI, just Docker API                      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Option C: Abstract Runtime

Create a FreeBSD-specific container runtime abstraction (similar to the Apple Container skill).

Option D: No Containers (Raw)

Run the agent directly on the FreeBSD host.

Option D+: Jail-Based Isolation native alternative

Use FreeBSD jails with nullfs mounts to isolate agents — no Docker, no Linux VM, pure FreeBSD.

┌─────────────────────────────────────────────────────────────────┐
│  FreeBSD 15 Host                                                │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  Jail: nanoclaw                                         │   │
│  │                                                         │   │
│  │  /home/nanoclaw/     ← nullfs RO (host:/home/nanoclaw) │   │
│  │  /groups/            ← nullfs RW (host:/path/groups)   │   │
│  │  /data/              ← nullfs RW (host:/path/data)     │   │
│  │  /workspace/ipc/     ← nullfs RW (host:/path/ipc)      │   │
│  │                                                         │   │
│  │  ├── Node.js 22 (installed in jail)                   │   │
│  │  ├── Chromium (installed in jail)                     │   │
│  │  ├── claude-code CLI (installed in jail)              │   │
│  │  └── Agent runs here, can ONLY see jail filesystem    │   │
│  │                                                         │   │
│  │  Even "rm -rf /" only destroys the jail, not host     │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                │
│  Host is protected — jail has no access to /etc, /root, etc.  │
│                                                                │
└─────────────────────────────────────────────────────────────────┘

3. Option B vs Option D+

Two viable approaches emerged from this exploration:

Option B (Docker VM) — Zero Code Changes

The container-runtime.ts file in Clawdie is already an abstraction layer — only 87 lines, designed to be swappable. The only change needed:

# In .env on FreeBSD host:
DOCKER_HOST=tcp://10.0.0.2:2375

That's it. The Node.js process thinks it's talking to local Docker, but it's actually talking to Docker inside the VM.

Option D+ (Jail) — Native FreeBSD Performance

For a small code change (5 environment variables), you get native FreeBSD performance with real isolation. The agent-runner's hardcoded paths become configurable:

# Environment variables for jail mode:
NANOCLAW_IPC_DIR=/workspace/ipc/input
NANOCLAW_WORKSPACE=/groups/main
NANOCLAW_CONVERSATIONS_DIR=/groups/main/conversations
NANOCLAW_GLOBAL_MD=/workspace/global/CLAUDE.md
NANOCLAW_EXTRA_DIR=/workspace/extra

Key insight

Clawdie's architecture already separates concerns:

4. Setup Guide (Option B)

Prerequisites

• FreeBSD 15 with root access
• bhyve support (most modern hardware)
• 8GB+ RAM recommended
• ZFS pool for snapshots

Step 1: Create the Docker VM

# Install vm-bhyve (VM manager)
pkg install vm-bhyve

# Create ZFS dataset for VMs
zfs create -o mountpoint=/vms zroot/vms

# Initialize vm-bhyve
sysrc vm_enable="YES"
sysrc vm_dir="zfs:zroot/vms"
vm init

# Download Alpine Linux (minimal, ~50MB)
vm iso https://dl-cdn.alpinelinux.org/alpine/v3.20/releases/x86_64/alpine-virt-3.20.0-x86_64.iso

# Create VM (512MB RAM, 1 vCPU, 4GB disk)
vm create -t alpine -s 4G -m 512M -c 1 docker-vm

# Install Alpine
vm install docker-vm alpine-virt-3.20.0-x86_64.iso

Step 2: Configure Alpine for Docker

# Inside the VM console:
vm console docker-vm

# Setup Alpine
setup-alpine  # Choose "sys" mode for disk install

# After reboot, install Docker
apk add docker
rc-update add docker boot
service docker start

# Enable TCP API (edit /etc/init.d/docker or use override)
# Create /etc/docker/daemon.json:
{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}

# Restart Docker
service docker restart

Step 3: Network Bridge

# On FreeBSD host, create bridge for VM communication
# Add to /etc/rc.conf:
cloned_interfaces="bridge0"
ifconfig_bridge0="addm em0"  # Replace em0 with your NIC

# Configure VM with static IP (edit /vms/docker-vm/vm.conf)
# Add network config to get 10.0.0.2 or use DHCP

Step 4: Install Clawdie on FreeBSD

# Install Node.js 22
pkg install node22 npm

# Clone Clawdie
git clone https://codeberg.org/Clawdie/nanoclaw.git /home/nanoclaw
cd /home/nanoclaw

# Install dependencies
npm install

# Build
npm run build

# Configure Docker host
echo "DOCKER_HOST=tcp://10.0.0.2:2375" >> .env

Step 5: Build Agent Image

# On FreeBSD host, tell Docker (in VM) to build the image
DOCKER_HOST=tcp://10.0.0.2:2375 docker build -t nanoclaw-agent:latest container/

# Verify
DOCKER_HOST=tcp://10.0.0.2:2375 docker images

Step 6: Configure Telegram

Use the /add-telegram skill to add Telegram support (replaces WhatsApp):

# Create bot with @BotFather, get token
# Add to .env:
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_ONLY=true

4.5 Setup Guide (Option D+ — Jail-Based)

This approach uses FreeBSD's native jail system instead of Docker. The agent runs isolated but shares the host kernel — no VM overhead.

Code Changes Required

The agent-runner has 5 hardcoded paths. Make them configurable:

// In container/agent-runner/src/index.ts, change:

// Before (hardcoded):
const IPC_INPUT_DIR = '/workspace/ipc/input';
const conversationsDir = '/workspace/group/conversations';
const globalClaudeMdPath = '/workspace/global/CLAUDE.md';
const extraBase = '/workspace/extra';
cwd: '/workspace/group'

// After (configurable):
const IPC_INPUT_DIR = process.env.NANOCLAW_IPC_DIR || '/workspace/ipc/input';
const conversationsDir = process.env.NANOCLAW_CONVERSATIONS_DIR || '/workspace/group/conversations';
const globalClaudeMdPath = process.env.NANOCLAW_GLOBAL_MD || '/workspace/global/CLAUDE.md';
const extraBase = process.env.NANOCLAW_EXTRA_DIR || '/workspace/extra';
// cwd becomes: process.env.NANOCLAW_WORKSPACE || '/workspace/group'

Step 1: Install bastille (Jail Manager)

# bastille is the modern FreeBSD jail manager
pkg install bastille

# Enable it
sysrc bastille_enable="YES"

# Initialize with ZFS
bastille bootstrap zfs

Step 2: Create the Jail

# Create a thin jail (uses ZFS snapshots, minimal disk)
bastille create nanoclaw 15.0-RELEASE 10.0.0.10

# Or use a base template for faster creation:
bastille create -T nanoclaw 15.0-RELEASE 10.0.0.10

Step 3: Install Dependencies in Jail

# Enter the jail
bastille console nanoclaw

# Inside jail:
pkg install node22 npm chromium

# Install claude-code globally
npm install -g @anthropic-ai/claude-code

# Verify Chromium works
chromium --version

Step 4: Configure nullfs Mounts

# On HOST, edit /etc/jail.conf.d/nanoclaw.conf or bastille config:
# Mount Clawdie code (read-only for safety)

# Create mount points in jail first:
bastille exec nanoclaw mkdir -p /home/nanoclaw /groups /data /workspace/ipc

# Add to /etc/fstab (host):
/home/nanoclaw  /jails/nanoclaw/root/home/nanoclaw  nullfs  ro   0 0
/home/nanoclaw/groups/main  /jails/nanoclaw/root/groups/main  nullfs  rw  0 0
/home/nanoclaw/data  /jails/nanoclaw/root/data  nullfs  rw  0 0
/home/nanoclaw/data/ipc  /jails/nanoclaw/root/workspace/ipc  nullfs  rw  0 0

# Or use bastille's mount command:
bastille mount nanoclaw /home/nanoclaw /home/nanoclaw nullfs ro
bastille mount nanoclaw /home/nanoclaw/groups/main /groups/main nullfs rw
bastille mount nanoclaw /home/nanoclaw/data /data nullfs rw

Step 5: Create Jail Runner Script

Replace Docker container spawn with jail exec:

#!/bin/sh
# run-agent-in-jail.sh

JAIL_NAME="nanoclaw"
GROUP_FOLDER="$1"
PROMPT="$2"

# Environment for agent-runner
export NANOCLAW_IPC_DIR="/workspace/ipc/input"
export NANOCLAW_CONVERSATIONS_DIR="/groups/${GROUP_FOLDER}/conversations"
export NANOCLAW_WORKSPACE="/groups/${GROUP_FOLDER}"
export NANOCLAW_GLOBAL_MD="/workspace/global/CLAUDE.md"
export NANOCLAW_EXTRA_DIR="/workspace/extra"

# Run agent inside jail
echo "{\"prompt\":\"${PROMPT}\",\"groupFolder\":\"${GROUP_FOLDER}\"}" | \
  bastille exec $JAIL_NAME node /home/nanoclaw/container/agent-runner/dist/index.js

Step 6: Modify container-runner.ts

// In src/container-runner.ts, add jail mode:

const USE_JAIL = process.env.NANOCLAW_USE_JAIL === 'true';

if (USE_JAIL) {
  // Spawn process in jail instead of Docker container
  const jail = spawn('bastille', [
    'exec', 'nanoclaw',
    'node', '/home/nanoclaw/container/agent-runner/dist/index.js'
  ], { stdio: ['pipe', 'pipe', 'pipe'] });
  
  // Rest is same — stdin JSON, stdout parsing, etc.
} else {
  // Existing Docker code...
}

Step 7: Jail Security Hardening

# In jail.conf, add restrictions:
nanoclaw {
  host.hostname = nanoclaw;
  ip4.addr = 10.0.0.10;
  path = /jails/nanoclaw/root;
  
  # Security settings
  securelevel = 2;
  enforce_statfs = 2;
  children.max = 0;
  allow.raw_sockets = 0;
  allow.sysvipc = 0;
  allow.mount = 0;
  allow.mount.devfs = 0;
  allow.quotas = 0;
  
  # Network restrictions (optional)
  interface = lo1;
}

# Create loopback interface for jail isolation:
cloned_interfaces="lo1"
ifconfig_lo1_name="jail0"

Architecture Comparison

5. tmux Glass-Pane for Clawdie adaptable

The tmux glass-pane concept from Clawdie adapts perfectly to Clawdie. Instead of watching an OpenClaw gateway, you watch Clawdie's main process + container logs.

3-Pane Layout

┌─────────────────────────────────────────────────────────────────┐
│                    tmux session: nanoclaw                       │
├────────────────────────────┬────────────────────────────────────┤
│                            │                                    │
│   Clawdie main process    │         Interactive shell          │
│   (npm start / dev)        │      (for debugging, tests)        │
│                            │                                    │
│   [agent spawning logs]    │      $ sqlite3 store/messages.db   │
│   [message routing]        │      $ tail -f logs/nanoclaw.log   │
│   [IPC activity]           │                                    │
│                            │                                    │
├────────────────────────────┴────────────────────────────────────┤
│                                                                 │
│   btop / htop (system monitoring)                               │
│   - Container CPU/RAM usage                                     │
│   - FreeBSD host resources                                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Start Script: start-nanoclaw.sh

#!/bin/sh
# start-nanoclaw.sh — tmux glass-pane launcher for FreeBSD

SESSION="nanoclaw"
PROJECT="/home/nanoclaw"

# Kill existing session if any
tmux kill-session -t $SESSION 2>/dev/null

# Create new session with main process
tmux new-session -d -s $SESSION -c $PROJECT

# Split horizontally (shell on right)
tmux split-window -h -t $SESSION

# Split bottom (monitor)
tmux split-window -v -t $SESSION:0.0

# Pane 0: Clawdie main process
tmux send-keys -t $SESSION:0.0 'cd /home/nanoclaw && DOCKER_HOST=tcp://10.0.0.2:2375 npm start' Enter

# Pane 1: Shell
tmux send-keys -t $SESSION:0.1 'cd /home/nanoclaw' Enter

# Pane 2: btop (or htop)
tmux send-keys -t $SESSION:0.2 'btop' Enter

# Set layout
tmux select-layout -t $SESSION main-horizontal

# Attach
tmux attach -t $SESSION

Access Patterns

6. Stripe Integration preinstalled

This instance comes with Stripe Agents toolkit preconfigured for payment processing. The agent can handle customer lookups, payment links, subscriptions, and billing operations.

Integration Paths

Configuration

# In .env (NOT committed to repo):
STRIPE_SECRET_KEY=rk_test_...   # Restricted API Key (test mode)
STRIPE_WEBHOOK_SECRET=whsec_... # For webhook verification

# MCP config (for Claude/Cursor integration):
# See .claude/mcp-servers.json.example

Available Operations

Example: Customer Lookup

# Via Telegram to Clawdie:
"Look up customer john@example.com in Stripe"

# Agent will:
# 1. Search Stripe customers by email
# 2. Return payment history, subscription status
# 3. Offer actions (update, refund, etc.)

Resources

• Stripe Agents Documentation
• GitHub: stripe/ai
• Stripe MCP Documentation

7. Security Considerations

Docker TCP API

TLS Setup (Recommended)

# On Docker VM, generate certs
apk add openssl
mkdir -p /etc/docker/certs
cd /etc/docker/certs

# Generate CA
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem

# Generate server cert
openssl genrsa -out server-key.pem 4096
openssl req -new -key server-key.pem -out server.csr
openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem

# Generate client cert (for FreeBSD host)
openssl genrsa -out key.pem 4096
openssl req -new -key key.pem -out client.csr
openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out cert.pem

# Update /etc/docker/daemon.json:
{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],
  "tls": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem"
}

# Copy ca.pem, cert.pem, key.pem to FreeBSD host
# Set DOCKER_HOST and DOCKER_TLS_VERIFY:
export DOCKER_HOST=tcp://10.0.0.2:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/home/nanoclaw/docker-certs

FreeBSD Firewall (pf)

# /etc/pf.conf
# Block Docker API from external access
block in on egress proto tcp from any to any port 2375:2376

# Allow only from localhost and internal bridge
pass in on bridge0 proto tcp from 10.0.0.0/24 to any port 2375:2376

8. Comparison: All Options

When to choose each option

9. Open Questions

1. Jail vs Docker VM performance — Benchmark agent spawn time and memory usage for both approaches.
2. Chromium in jail — Does Chromium require special permissions or sysctls inside a jail?
3. bastille vs ezjail vs iocage — Which jail manager is best for this use case?
4. nullfs performance — Any I/O penalty for nullfs mounts vs native?
5. VNET jails — Should the jail have its own network stack (VNET) for additional isolation?
6. Agent-runner refactor — Should we upstream the configurable paths to Clawdie?

10. Next Steps

Option B (Docker VM)

• ☐ Set up FreeBSD 15 test environment
• ☐ Install vm-bhyve and create Alpine Docker VM
• ☐ Test DOCKER_HOST=tcp://... from FreeBSD to VM
• ☐ Build nanoclaw-agent image
• ☐ Run Clawdie with Telegram channel
• ☐ Benchmark agent spawn latency

Option D+ (Jail)

• ☐ Add configurable paths to agent-runner (5 env vars)
• ☐ Create jail with bastille
• ☐ Install Node.js + Chromium in jail
• ☐ Configure nullfs mounts
• ☐ Add jail spawn mode to container-runner.ts
• ☐ Test agent execution inside jail
• ☐ Compare spawn time vs Docker VM
• ☐ Create jail setup script / skill

Shared

• ☐ Create start-nanoclaw.sh with tmux glass-pane
• ☐ Document TLS setup for Docker API (production)
• ☐ Write comparison benchmarks
• ☐ Create FreeBSD skill for Clawdie

11. Forking This Repo

This document and the associated configuration are open source. Fork it, adapt it, run your own instance.

Repository

git clone https://codeberg.org/Clawdie/clawdie.git
cd clawdie

What's Included

What's NOT Included (Sensitive)

Quick Start After Fork

# 1. Copy environment template
cp .env.example .env

# 2. Edit with your values
vim .env
# Required:
#   - TELEGRAM_BOT_TOKEN (from @BotFather)
#   - ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN
# Optional:
#   - STRIPE_SECRET_KEY (for payments)
#   - DOCKER_HOST (if using Docker VM)

# 3. Install dependencies
npm install

# 4. Build
npm run build

# 5. Start (choose one)
./scripts/start-clawdie.sh    # tmux glass-pane
npm start                      # direct

# 6. Register your Telegram chat
# Send /chatid to your bot, then register via IPC

Customization Points

Branches

# Check for accidental secrets:
grep -r "sk_live\|rk_live\|whsec_\|TOKEN=" . --include="*.ts" --include="*.js" --include="*.env"

# Verify .gitignore is working:
git status --porcelain | grep -E "\.env|credentials|\.pem|\.key"

# Should return nothing!