Fabric Scaffold v10

A SYSTEM
INSIDE A
SYSTEM.

Docker-native distributed execution platform. One command spawns a full Ubuntu node, control plane gateway, NATS JetStream message bus, and AI reflector — all wired together, all token-protected.

↗ Get it on Gumroad Quickstart →

One-time £19.99

blockbrain — docker compose up --build

[+] Building 185.4s (42/42) FINISHED => [fabric_node 1/17] FROM ubuntu:24.04 18.2s => [fabric_node 4/17] RUN curl tailscale 22.5s => [fabric_node 7/17] RUN pip install -r 34.2s => [fabric_node] exporting to image 22.7s ✔ Image fabric_scaffold-fabric_node Built ✔ Image fabric_scaffold-gateway Built ✔ Image fabric_scaffold-reflector Built ✔ Volume fabric_pgdata Created ✔ Container fabric-postgres Created ✔ Container fabric-nats Created ✔ Container fabric-gateway Created ✔ Container fabric-node Created ✔ Container fabric-reflector Created Attaching to fabric-gateway, fabric-nats, fabric-node, fabric-postgres, fabric-reflector fabric-gateway | INFO: Gateway ready on :9000 fabric-node | INFO: Node UI ready on :8000 fabric-reflector | INFO: Subscribed to fabric.> blockbrain@blockbrain:~/fabric_scaffold$

Architecture

FOUR PLANES.
ONE COMMAND.

Control, execution, observability, and network — each a container, each independently replaceable, all wired through NATS JetStream.

Layer 1 — Control

Gateway

Service registry, heartbeat monitor, NATS→WebSocket bridge, and unified dashboard. The nervous system.

:9000 — Dashboard + API

/api/register — Service mesh

/api/services — Discovery

Layer 2 — Execution

Fabric Node

Full Ubuntu 24.04 userspace inside Docker. PTY terminal, job runner, file browser, optional SSH + Tailscale.

:8000 — Node web UI

:2222 — SSH access

Tailscale — mesh overlay

Layer 3 — Observability

Reflector

Subscribes to all fabric.> NATS events. Builds observations, emits suggestions. Plug in your LLM here.

:8888 — Reflector UI

NATS fabric.> — full stream

Suggestions API

Optional — Privileged

NetCtl

Network namespace primitives. Veth pairs, NAT, routing. Only runs in --profile privileged. Token-gated.

:9010 — NetCtl API

ns_cli — namespace CLI

netns / veth operations

Shared infra: NATS 2.10 JetStream → persistent event log | PostgreSQL 16 → state | Redis 7 → optional cache | All ports bound 127.0.0.1 → safe by default

Features

BUILT TO RUN.
NOT TO DEMO.

Every component has been run in production. v106 has been up for 5 days straight on real hardware while this was being sold.

🔐

Token Auth — Fail Closed

X-Fabric-Token enforced across HTTP, WebSocket, and SSH. Missing token = hard reject. Secrets generated at runtime, never baked into images.

📡

NATS JetStream Message Bus

Persistent, replay-capable event stream on fabric.> subjects. Services self-register and heartbeat. Dead services are detected automatically.

🖥️

Full Ubuntu Userspace

Real Ubuntu 24.04 inside Docker. Not alpine, not distroless. PTY terminal, apt-get, Python venv, SSH — the whole thing.

🌐

Tailscale Mesh Networking

Set TAILSCALE_AUTHKEY and the node joins your tailnet automatically. Access from anywhere without opening a single firewall port.

🧠

AI Reflector — Plug In Your LLM

The Reflector subscribes to every event and emits structured suggestions. Wire in Ollama, Groq, or OpenAI — the interface is already there.

🔌

Service Mesh — Self-Registering

Services POST /api/register on boot. Gateway tracks health via heartbeats. Capabilities, labels, and metrics all queryable via JSON API.

🗄️

PostgreSQL + Volumes Baked In

Postgres 16 with healthcheck, named volumes, and an init SQL script. Data survives container restarts. Ready for your schema.

🕸️

Network Namespace Control

Privileged profile adds fabric_netctl — a token-gated API for veth pairs, netns, NAT, and ns_cli for direct namespace operations.

📦

One Tar. One Command.

Extract, run ./scripts/init.sh to generate secrets, docker compose up. Five minutes from zero to running distributed system.

Quickstart

UP IN FIVE
MINUTES.

No Kubernetes, no Helm charts, no cloud account. Just Docker and a terminal.

Extract and generate secrets

The init script generates FABRIC_TOKEN, POSTGRES_PASSWORD, and SSH credentials. Nothing is baked in.

        $ tar -xzf fabric_scaffold_v10.tar.gz

        $ cd fabric_scaffold_v10

        $ ./scripts/init.sh

        # Generates .env with secrets

Build and launch

Core profile: Gateway + Node + Reflector + NATS + Postgres. Add --profile privileged for NetCtl.

        $ docker compose up --build

        # 185 seconds first build

        # Much faster on rebuild (cached)

Open the dashboards

All three UIs are live. Grab your FABRIC_TOKEN from .env and append it to the URL.

        # Gateway (control plane)

        http://localhost:9000/ui?token=<TOKEN>

        # Fabric Node (terminal + jobs)

        http://localhost:8000/?token=<TOKEN>

        # Reflector (event stream)

        http://localhost:8888/?token=<TOKEN>

SSH into the node

Full Ubuntu shell inside the container. Inspect, install, run jobs — it's a real environment.

        $ ssh fabric@localhost -p 2222

        # Password in .env → FABRIC_SSH_PASSWORD

        # Or add Tailscale and access from anywhere:

        # TAILSCALE_AUTHKEY=tskey-... in .env

What's Inside

EVERY FILE.
EXPLAINED.

No mystery. No minified blobs. Real Python, real shell, real Dockerfiles — all readable.

fabric_scaffold_v10/

📄 docker-compose.yml 📄 .env.example 📄 README.md 📄 ARCHITECTURE.md 📄 CHANGELOG.md 📁 gateway/ │ Dockerfile │ main.py 📁 services/ │ fabric_node/ │ │ Dockerfile │ │ entrypoint.sh │ │ tool.py │ fabric_reflector/ │ │ app.py │ fabric_netctl/ │ │ main.py │ │ ns_cli.sh 📁 shared/ │ schemas.py │ security.py │ fabric_client.py 📁 infra/ │ init-db.sql 📁 scripts/ │ init.sh │ self_test.sh

gateway/main.py

FastAPI Control Plane — v9.0 Gateway

Service registry with heartbeat tracking, NATS subscription bridged to WebSocket clients, HTTP dispatch layer. Token auth via shared security module. Async throughout.

services/fabric_node/entrypoint.sh + tool.py

Ubuntu Execution Node

Entrypoint configures SSH keys, optionally starts tailscaled, and launches the node service. tool.py exposes PTY terminal, job runner, and file browser over HTTP/WebSocket.

services/fabric_reflector/app.py

Event Observer + AI Hook Point

Subscribes to all fabric.> NATS subjects. Aggregates event patterns into observations and emits suggestions. This is where you wire in Ollama, Groq, or any LLM.

shared/security.py + schemas.py

Shared Auth + Pydantic Models

Token validation used by every service. Pydantic v2 schemas for services, jobs, transfers, events, and dispatch — all typed and validated at the boundary.

services/fabric_netctl/ns_cli.sh

Network Namespace CLI

Shell script for creating/destroying network namespaces, veth pairs, and NAT rules. Pairs with the token-gated HTTP API for programmatic network topology control.

scripts/init.sh + self_test.sh

Secrets Generator + Smoke Test

init.sh creates a .env with random FABRIC_TOKEN, Postgres password, and SSH credentials. self_test.sh hits each endpoint and verifies auth is working correctly.

A SYSTEMINSIDE ASYSTEM.

FOUR PLANES.ONE COMMAND.

BUILT TO RUN.NOT TO DEMO.

UP IN FIVEMINUTES.

EVERY FILE.EXPLAINED.

A SYSTEM
INSIDE A
SYSTEM.

FOUR PLANES.
ONE COMMAND.

BUILT TO RUN.
NOT TO DEMO.

UP IN FIVE
MINUTES.

EVERY FILE.
EXPLAINED.