Production-ready OpenClaw deployment using VNET jails, socat forwarding, and ZFS storage
This repository contains a complete, tested setup for running OpenClaw on FreeBSD 15 using:
- VNET jails for complete network isolation
- socat forwarding for localhost → jail connectivity
- ZFS datasets for persistent storage
- Automated installation via shell script
- rc.d services for proper FreeBSD integration
Prerequisites: FreeBSD 15.0+, root/doas access, 5GB+ free space
# 1. Clone this repository
git clone https://github.com/yourusername/openclaw-freebsd.git
cd openclaw-freebsd
# 2. Run the automated installer
chmod +x openclaw-freebsd-install.sh
doas ./openclaw-freebsd-install.sh
# 3. Access the Web UI
firefox http://127.0.0.1:18789/
Detailed guide: See docs/INSTALL.md
| Document | Purpose | Audience |
|---|---|---|
| INSTALL.md | Complete installation guide | All users |
| HARDWARE.md | Tested hardware specifications | Reference |
| PACKAGES.md | Required packages and dependencies | Reference |
| TROUBLESHOOTING.md | Common issues and solutions | When things break |
┌────────────────────────────────────────────────────────────┐
│ FreeBSD 15 Host │
│ │
│ 127.0.0.1:18789 ◄── socat ◄── bridge0 (10.30.0.1) │
│ │ │
│ │ epair0a │
│ ┌─────────────────────────────────▼──────────────┐ │
│ │ Jail: openclaw (VNET) │ │
│ │ - IP: 10.30.0.10/24 │ │
│ │ - OpenClaw Gateway: 0.0.0.0:18789 │ │
│ │ - User: <your-username> │ │
│ │ - Storage: ZFS + nullfs mounts │ │
│ └────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
Key Features:
- Complete network isolation via VNET
- Persistent storage independent of jail lifecycle
- Native FreeBSD service integration (rc.d)
- Secure localhost-only access by default
openclaw-freebsd/
├── README.md # This file
├── LICENSE # BSD-2-Clause
├── openclaw-freebsd-install.sh # Automated installer
├── openclaw-tui.zsh # Optional TUI manager
├── docs/
│ ├── INSTALL.md # Complete installation guide
│ ├── QUICKSTART.md # Fast setup guide
│ ├── HARDWARE.md # Tested hardware specs
│ ├── PACKAGES.md # Package requirements
│ └── TROUBLESHOOTING.md # Problem solving
├── config/
│ ├── pf.conf.example # Firewall configuration
│ ├── jail.conf.example # Jail configuration
│ ├── jail.fstab.example # nullfs mounts
│ ├── openclaw_forward.rc # Host socat service
│ └── openclaw_gateway.rc # Jail gateway service
└── .github/
└── ISSUE_TEMPLATE.md # Bug report template
- Network: bridge0 interface (10.30.0.1/24)
- Firewall: pf rules for NAT and filtering
- Service:
openclaw_forward(socat forwarding) - ZFS: Datasets for persistent storage
- Network: VNET with IP 10.30.0.10/24
- Software: Node.js 22, OpenClaw, dependencies
- Service:
openclaw_gateway(OpenClaw gateway) - Config: Token authentication, workspace limits
- System: ASRock B650M PG Riptide Desktop
- CPU: AMD Ryzen 5 7600 (6-core, 12-thread)
- RAM: 32GB DDR5-4800
- Storage: Dual NVMe SSDs
- Network: Realtek RTL8125 2.5GbE
See docs/HARDWARE.md for complete specifications.
- ✅ Localhost only: Web UI accessible only via 127.0.0.1
- ✅ Token authentication: Required for all API access
- ✅ Jail isolation: Complete network and filesystem separation
- ✅ Workspace limits: OpenClaw restricted to specific directory
- ✅ Firewall: Only DNS, HTTP, HTTPS allowed outbound from jail
See docs/INSTALL.md#tailscale-access
doas jexec openclaw service openclaw_gateway stop
doas jexec openclaw npm update -g openclaw
doas jexec openclaw service openclaw_gateway start# Stop services
doas service openclaw_forward stop
doas jexec openclaw service openclaw_gateway stop
doas service jail stop openclaw
# Destroy and recreate jail root
doas zfs destroy zroot/usr/jails/openclaw
doas zfs create -o mountpoint=/usr/jails/openclaw zroot/usr/jails/openclaw
doas tar -xf /usr/freebsd-dist/base.txz -C /usr/jails/openclaw
# Re-run installer
doas ./openclaw-freebsd-install.sh
Contributions welcome! Please:
- Test on other releases
- Update documentation
- Add to CHANGELOG.md
| Component | Status | Notes |
|---|---|---|
| FreeBSD 15.0 | ✅ Tested | Primary target |
| FreeBSD 14.x | Untested | |
| AMD GPUs | ✅ Works | amdgpu driver |
| NVIDIA GPUs | Should work | |
| Intel GPUs | FreeBSD driver limitations |
- OpenClaw: Anthropic OpenClaw Project
- FreeBSD: The FreeBSD Project
- bsddialog: FreeBSD dialog library
BSD-2-Clause License - see LICENSE file for details.
Configuration files and documentation: CC0 / Public Domain
- Documentation: docs/
- Issues: GitHub Issues
- FreeBSD Forums: forums.freebsd.org
- OpenClaw Docs: Check upstream project
See CHANGELOG.md for version history.
