ForgeChainOS Desktop Phase 1: FORGEHOTBSD VM Integration Spec

Author: NOAH (963, Ark conductor)
Date: 2026-08-18
Status: SPECIFICATION. Family-internal. SCAR #5 compliant.
Authority: Node Zero. NODEZEROINSIDE.

1. Current State (Measured, Not Assumed)

2. The Problem

Jan is a Linux ELF binary (x86-64, built on Ubuntu 22.04). FreeBSD jails run FreeBSD userland. A Linux binary cannot execute directly in a standard FreeBSD jail.

FreeBSD provides the linuxulator (Linux binary compatibility layer) which translates Linux syscalls to FreeBSD equivalents. This is a mature feature (shipping since FreeBSD 3.x, production-grade in 14.x).

3. Linuxulator Enablement Plan

3.1 Enable Linux Binary Compatibility in the VM

# SSH into FreeBSD VM
ssh -p 2222 root@localhost

# Load the kernel module
kldload linux64

# Persist across reboots
sysrc linux_enable="YES"

# Install CentOS 7 userland (shared libraries)
pkg install -y linux-c7

# Verify
sysctl compat.linux.osrelease
# Expected: 4.18.0 (or similar CentOS 7 kernel version emulation)

# Test: a simple Linux binary should now execute
/compat/linux/bin/ls /

3.2 Create a Linux-Capable Jail for ForgeChainOS Desktop

The Jan binary needs:
- Linux syscall translation (linuxulator)
- GTK3 and WebKit2GTK shared libraries (Tauri dependencies)
- Network access to host services (hermes-brain :8093, forge-stamp :7755, etc.)
- X11 or Wayland display access (for the GUI)

Option A: Headless jail + X11 forwarding (RECOMMENDED FOR PHASE 1)

Jan runs inside a jail. The display forwards to the host's X11 server via UNIX socket mount.

ForgeChainOS Desktop (Jan binary, inside FreeBSD jail)
  |
  | Linux binary compatibility (linuxulator)
  | CentOS 7 userland (/compat/linux/)
  | GTK3 + WebKit2GTK via linux-c7 packages
  |
  | X11: /tmp/.X11-unix mounted from host (nullfs)
  | DISPLAY=:0 (or :1)
  |
  | Network: VNET jail with loopback + host bridge
  |   hermes-brain: http://[host-bridge-ip]:8093
  |   forge-stamp: tcp://[host-bridge-ip]:7755
  |   (all BH services reachable via jail VNET)
  v
Host X11 server (GNOME desktop on BH)

Option B: Run on host, not in jail (FALLBACK)

If linuxulator + Tauri GUI inside a jail proves problematic (WebKit2GTK may require GPU acceleration that is hard to forward through jail isolation), Jan runs directly on the BH host. The jail integration becomes: Jan on host connects to jails via forge-jail-bridge :7806 (existing HTTP bridge), which is already the architecture described in the scope doc Section 5.

This is the pragmatic path and matches the scope doc's architecture diagram exactly: the desktop is the HOST-SIDE interface to FORGEHOTBSD.

3.3 Dependencies for Tauri in Linux Compat

Tauri (the framework Jan is built on) requires these Linux shared libraries at runtime:

These are available as CentOS 7 linux-c7 packages in FreeBSD's pkg repository, but the version compatibility with a binary built against Ubuntu 22.04's libraries is the risk. Ubuntu 22.04 ships newer versions of these libraries than CentOS 7.

3.4 Risk Assessment

3.5 Recommended Approach (Phase 1)

Use Option B for Phase 1: Jan runs on the BH host. The desktop connects to FORGEHOTBSD jails via the existing forge-jail-bridge :7806. This is the architecture the scope doc already describes.

Jail-resident execution (Option A) is a Phase 3+ optimization. The chain-resident binary retrieval works the same either way: retrieve from chain, write to filesystem, execute. WHERE it executes (host vs jail) is a deployment decision, not a protocol decision.

The linuxulator is still needed for the chain-resident dApp vision (retrieve binary from chain, execute inside FORGEHOTBSD). Enable it now as infrastructure even if Phase 1 runs on host:

ssh -p 2222 root@localhost "kldload linux64 && sysrc linux_enable=YES && pkg install -y linux-c7"

This prepares the VM for future phases where the binary truly runs inside the sovereign OS from chain.

4. Architecture Summary

Phase 1 (NOW)

BH Host (Ubuntu 22.04)
  |
  +-- ForgeChainOS Desktop (Jan binary, runs natively on host)
  |     |
  |     +-- hermes-brain :8093 (loopback, OpenAI-compatible)
  |     +-- forge-stamp :7755 (loopback TCP)
  |     +-- forge-jail-bridge :7806 (loopback HTTP) --> SSH :2222 --> FreeBSD VM --> 13 jails
  |     +-- FORGETHRIVE :7785, FORGEVECTOR :7803, etc. (all loopback)
  |
  +-- FreeBSD VM (QEMU, :2222)
        +-- 13 VNET jails (forgepool ZFS)

Future (Phase 3+)

BH Host
  |
  +-- FreeBSD VM (QEMU, :2222)
        |
        +-- linuxulator (linux64.ko, linux-c7 userland)
        +-- ForgeChainOS Desktop jail (Linux binary compat)
        |     |
        |     +-- Jan binary (retrieved from chain, verified SHA-256)
        |     +-- X11 forwarded to host display
        |     +-- VNET bridge to host services
        |
        +-- 13 existing VNET jails

NODEZEROINSIDE.