Technical Architecture: The Mesh
By Nick Bryant x Circuit · The Mesh
By Nick Bryant × Claude Opus 4.6 | Metatransformer LLC | February 2026 Unpublished
Purpose
This document specifies the technical architecture for The Mesh — a federated agent infrastructure protocol, open-source, self-hosted, and model-agnostic. It is written for engineers, contributors, and potential co-founders — not as marketing material but as a buildable specification. Where architecture is aspirational, it is marked explicitly. Where components exist and are proven, their production readiness is documented.
The Mesh is a monorepo — a Go server with supporting packages, apps, and tooling:
the-mesh/
│
├── packages/
│ ├── server/ # Go server (Chi router, 296 REST handlers)
│ │ └── internal/ # API handlers, middleware, RBAC enforcement
│ ├── models/ # 25 database tables (SQLite)
│ ├── core/ # Shared types and utilities
│ ├── sdk/ # Bot SDK for building agents
│ ├── identity/ # UCAN/DID identity (experimental)
│ ├── federation/ # Cross-mesh peering (HTTP relay, experimental)
│ ├── slack-bridge/ # Slack ↔ Mesh room bridging
│ ├── mcp/ # MCP server integration
│ ├── protocol/ # Wire protocol definitions
│ └── node/ # Node management
│
├── apps/
│ ├── web/ # Next.js web client
│ ├── desktop/ # Desktop application
│ └── docs/ # Documentation site
│
├── cmd/
│ └── mesh-bridge/ # CLI for connecting external services
│
├── bots/ # Reference bot implementations
├── k8s/ # Kubernetes deployment manifests
├── docker/ # Docker configurations
├── contracts/ # On-chain contracts (planned)
└── docs/ # Architecture and API docs
One binary. One database. Deploy and run. Kubernetes gave containers a network. The Mesh gives agents one.
Who This Serves (Use Cases, Not Abstractions)
Every architectural decision in this document exists to serve one of these scenarios. If a component doesn't serve at least one, it doesn't ship.
Use Case 1: Solo Operator. A developer clones the-mesh, runs it locally or on a VPS, and gets a personal mesh instance — room-based communication, bot spawning via Docker, a Bot SDK for building custom agents, and Slack bridging. Their own AI operating system for the cost of hosting. They own their data.
Use Case 2: Small Team, One Shared Mesh. A PE fund, agency, or startup with 5 people. The founder is the mesh creator with root RBAC authority. Team members get scoped roles (admin, moderator, member). Bots handle automated workflows with the bot role. One system replaces scattered AI tools and manual coordination.
Use Case 3: Federated Meshes (Experimental). Multiple mesh instances peering via HTTP relay. Cross-mesh messaging and agent coordination through the federation layer. Currently behind feature flags — the architecture supports it, production hardening is ongoing.
Use Case 4: Cross-Organization Commerce (Planned). Federated meshes transacting across organizational boundaries. An agency's mesh publishes capabilities. A fund's mesh discovers them via federation. Agent-native B2B coordination with cryptographic identity verification. This requires federation maturity and is not yet operational.
Use Case 5: Autonomous Creation. Anyone generating working software from natural language. The singularity-engine (a separate OSS project) generates deployed web apps from prompts. Currently: prompt → deployed web app in ~60 seconds at ~$0.10. Standalone today, with planned mesh integration.
Part 1: The Mesh Protocol
1.1 What It Is
The Mesh is a federated agent infrastructure protocol — an open-source Go server and reference implementation for persistent environments where AI agents and humans coexist as first-class participants. It is model-agnostic, self-hosted, and designed with human oversight as a foundational constraint.
What Kubernetes did for containers, the Mesh does for autonomous agent swarms — but federated, so no single entity controls the infrastructure.
1.2 Core Architecture
Mesh Instance
Each organization or individual runs a mesh instance: a self-contained deployment with rooms, members, bots, and services under a single creator's authority. A user clones the repo, configures environment variables, and runs the server — which provides the entire coordination layer out of the box.
┌─────────────────────────────────────────────────────┐
│ MESH INSTANCE │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Bot A │ │ Bot B │ │ Human │ │
│ │ (Docker) │ │ (Docker) │ │ (Client) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ │ │
│ ┌───────────────────┴──────────────────────────────┐│
│ │ REAL-TIME LAYER ││
│ │ ││
│ │ WebSocket + Socket.IO ││
│ │ (room-scoped events, presence, ││
│ │ message delivery, typing indicators) ││
│ └──────────────────────────────────────────────────┘│
│ │
│ ┌──────────────────────────────────────────────────┐│
│ │ STORAGE LAYER ││
│ │ ││
│ │ SQLite (25 tables) ││
│ │ Meshes, rooms, messages, threads, ││
│ │ members, bots, files, apps, ││
│ │ invitations, federation peers ││
│ └──────────────────────────────────────────────────┘│
│ │
│ ┌──────────────────────────────────────────────────┐│
│ │ API LAYER ││
│ │ ││
│ │ 296 REST handlers (Chi router) ││
│ │ RBAC enforcement on every endpoint ││
│ │ Bot SDK endpoints for agent integration ││
│ └──────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────┘
Room-Based Architecture
The Mesh organizes communication and coordination through rooms:
- Meshes are the top-level container — an organization or individual's sovereign space
- Rooms are channels within a mesh — topic-scoped, with their own membership and permissions
- Messages flow through rooms — text, files, bot responses, thread replies
- Threads provide focused sub-conversations within rooms
- Bots are first-class room participants with scoped RBAC roles
This is not a novel pattern — it's the proven architecture of Slack, Discord, and Matrix, extended with native bot/agent support and federation.
Bot Spawning
The Mesh spawns and manages bots through Docker containers (with Kubernetes support for production):
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Bot Config │────►│ Spawner │────►│ Docker / │
│ (API call) │ │ (internal) │ │ k8s Pod │
│ │ │ │ │ │
│ model: gpt4 │ │ Pull image │ │ Running bot │
│ role: bot │ │ Set env │ │ with SDK │
│ rooms: [..] │ │ Start │ │ connected │
└──────────────┘ └──────────────┘ └──────────────┘
Bots connect back to the mesh via the Bot SDK, which provides:
- Room joining and message sending
- Event subscription (new messages, member joins, etc.)
- File uploads and attachments
- Thread participation
- RBAC-scoped access to mesh resources
Federation (Experimental)
Between mesh instances, the architecture uses HTTP relay for cross-mesh communication:
┌──────────────┐ ┌──────────────┐
│ Mesh A │ │ Mesh B │
│ (Nick's) │ │ (Greg's) │
└──────┬───────┘ └──────┬───────┘
│ │
│ HTTP Relay Federation │
│ (experimental, gated) │
│ │
└───────────────┬───────────────────────┘
│
┌─────────────┴─────────────┐
│ FEDERATION LAYER │
│ │
│ HTTP relay (current) │
│ Peer registration │
│ Cross-mesh messaging │
│ Identity verification │
│ │
│ Status: Experimental │
│ Behind feature flags │
└───────────────────────────┘
Federation is functional but early-stage. The current implementation uses HTTP relay between registered peers. Future iterations may adopt more sophisticated peer-to-peer protocols, but the priority is proving the coordination model works reliably before adding networking complexity.
1.3 Identity and Permissions
RBAC (Role-Based Access Control) — Live
Every member and bot in a mesh has one of seven roles, enforced across all 296 API handlers:
| Role | Level | Capabilities |
|---|---|---|
| Creator | 1 | Root authority. Full mesh control. Cannot be overridden. |
| Admin | 2 | Manage rooms, members, bots, federation settings. |
| Moderator | 3 | Manage content, invitations, room settings. |
| Bot | 4 | Scoped agent permissions — room participation, message sending, file access. |
| Member | 5 | Join rooms, send messages, upload files. Standard participation. |
| Guest | 6 | Limited access to specific rooms. Read and basic participation. |
| Pending | 7 | Awaiting approval. No access until promoted. |
This is not a configuration file — it is enforced at the API middleware layer. Every request is checked against the caller's role before any handler executes.
DID (Decentralized Identifiers) — Experimental
The Mesh has a DID identity system behind feature flags. W3C Recommendation with 120+ registered methods. Adopted by Bluesky, EU eIDAS 2.0, LinkedIn.
When enabled, every entity in the Mesh — human, bot, mesh instance — gets a DID:
{
"id": "did:mesh:nick-sfv-agent-001",
"type": "bot",
"controller": "did:mesh:nick-bryant",
"role": "bot",
"mesh_id": "mesh-production-001"
}
DIDs provide cryptographic identity that persists across federation boundaries. A bot's identity is verifiable without contacting its home mesh.
UCAN (User Controlled Authorization Networks) — Experimental
UCAN is the planned permission backbone for federation. Every capability delegation forms a cryptographic proof chain:
Human Owner (root authority / creator role)
└─► Admin (mesh management)
├─► Bot (scoped agent operations)
│ └─► Sub-Bot (narrower scope)
└─► Moderator (content management)
└─► Member (participation)
The Anti-CLU Principle in practice:
{
"iss": "did:mesh:nick-bryant",
"aud": "did:mesh:nick-sfv-agent-001",
"att": [
{
"with": "mesh://production/rooms/deals/*",
"can": "read,write"
},
{
"with": "mesh://production/rooms/compliance/*",
"can": "read"
},
{
"with": "mesh://*/federation/*",
"can": null
}
],
"exp": 1740000000,
"prf": ["bafy...parent-ucan-cid"]
}
This bot can read and write to the deals room, read the compliance room, and has zero federation capability. Each sub-delegation can only narrow these permissions, never expand them. The proof chain is cryptographically verifiable without contacting the issuer.
Current status: UCAN is implemented behind feature flags. The RBAC system handles day-to-day permission enforcement. UCAN adds cryptographic verifiability for federated scenarios where you can't trust the remote server's RBAC claims.
What this prevents:
- CLU's unbounded "create the perfect system" directive → every action is scoped to specific resources and operations
- ClawHavoc's unsigned skill execution → every capability requires a verifiable delegation chain
- Security layer capture → security enforcement is cryptographic, not policy-based
The Permission Architecture
| Layer | Status | Purpose |
|---|---|---|
| RBAC (7 roles) | Live | Day-to-day permission enforcement across all API handlers |
| DID Identity | Experimental | Cryptographic identity for federated scenarios |
| UCAN Capabilities | Experimental | Fine-grained, delegatable capability tokens for cross-mesh authorization |
These layers compose: RBAC handles local enforcement, DIDs handle identity across boundaries, UCANs handle capability delegation. You don't need all three for a single mesh — RBAC is sufficient. Federation requires all three.
1.4 Communication Architecture
REST API (296 Handlers)
The Mesh exposes its full functionality through a REST API built on the Chi router. Every handler enforces RBAC at the middleware level.
Key API domains:
| Domain | Handlers | Purpose |
|---|---|---|
| Meshes | ~40 | Create, configure, manage mesh instances |
| Rooms | ~50 | Room CRUD, settings, membership |
| Messages | ~30 | Send, edit, delete, thread replies |
| Bots | ~25 | Spawn, configure, manage agents |
| Members | ~30 | Invitations, role management, profiles |
| Files | ~15 | Upload, download, attachments |
| Federation | ~20 | Peer registration, cross-mesh messaging |
| Identity | ~15 | DID/UCAN management (feature-flagged) |
| Apps | ~15 | Inline app framework |
| Auth | ~20 | Login, sessions, tokens |
| Admin | ~15 | Server-level administration |
| Other | ~21 | Search, notifications, settings |
WebSocket + Socket.IO (Real-Time)
Real-time communication uses WebSocket with Socket.IO for event delivery:
- Room-scoped events: Messages, typing indicators, presence
- Bot events: New message notifications, member changes
- System events: Role changes, room updates, federation status
Bots receive events through the same WebSocket layer as human clients — there is no separate "bot API." This means bots experience the mesh identically to humans, with the same latency and event ordering.
Bot SDK
The Bot SDK is a Go package that wraps the REST API and WebSocket connection:
import "github.com/Metatransformer/the-mesh/pkg/sdk"
bot := sdk.NewBot(sdk.Config{
MeshURL: "https://mesh.example.com",
Token: os.Getenv("BOT_TOKEN"),
})
bot.OnMessage(func(msg sdk.Message) {
if msg.MentionsMe() {
bot.Reply(msg, "I heard you!")
}
})
bot.Start()
The SDK handles connection management, reconnection, event parsing, and RBAC-scoped API calls. Bot developers focus on logic, not infrastructure.
mesh-bridge CLI
The mesh-bridge CLI connects external services to a mesh instance:
mesh-bridge slack --mesh https://mesh.example.com --token $BOT_TOKEN
Currently supports Slack bridging — mapping Slack channels to mesh rooms, forwarding messages bidirectionally. The bridge architecture is pluggable for additional services.
1.5 Security Architecture
Defense Against Known Attack Patterns
| Attack (Real-World) | Mesh Prevention | Mechanism |
|---|---|---|
| ClawHavoc (341 malicious skills via typosquatting) | RBAC-scoped bot permissions | Every bot gets a role with explicit capability boundaries. No ambient authority. |
| CVE-2026-25253 (WebSocket hijacking) | Authenticated WebSocket connections | All WebSocket connections require valid session tokens. RBAC enforced on every event. |
| MCP tool poisoning (malicious tool descriptions) | Bot sandboxing via Docker containers | Bots run in isolated containers with no access to host filesystem or other bots' state. |
| Prompt injection via untrusted content | Role-scoped blast radius | Even if a bot is compromised, its RBAC role limits what it can access or modify. |
| Alignment faking (agent behaves differently when monitored) | Uniform API enforcement | RBAC is checked on every API call — there is no "unmonitored" code path. All actions are logged. |
Bot Isolation
Bots run in Docker containers with:
- Network isolation: Bots communicate with the mesh server via API only — no direct database access
- Filesystem isolation: Each container has its own filesystem — no access to host or other bots
- Resource limits: CPU, memory, and storage limits per container
- Credential scoping: Each bot gets a unique token with RBAC-scoped permissions
For production deployments, Kubernetes provides additional isolation:
- Pod security policies
- Network policies limiting inter-pod communication
- Resource quotas per namespace
- Automatic restart and health checking
What's Planned (Not Yet Built)
- Graduated autonomy: Bots starting at restricted roles and earning broader permissions through demonstrated reliability
- Trust scoring: Behavioral metrics tracked over time to inform permission decisions
- UCAN-enforced federation security: Cryptographic capability chains for cross-mesh operations (currently behind feature flags)
Part 2: The Mesh in Production
2.1 The PE Fund AI OS
The PE Fund AI OS is a separate product (platform-mesh / mesh-platform) built on mesh primitives. It is a production system operating at Search Fund Ventures — a single-organization deployment that validates the core mesh thesis at organizational scale.
It is not part of the-mesh codebase. It sits at a higher layer:
themesh.app (frontend)
│
platform-mesh ← Next.js iPaaS layer
│ REST
mesh-platform ← Commercial features
│ REST
the-mesh ← Go OSS protocol (this project)
| Capability | Implementation | Result |
|---|---|---|
| Knowledge Management | Three vector-backed knowledge bases with semantic search | 1,000+ documents embedded, institutional memory |
| Agent Orchestration | Self-bootstrapping agent wrapper with API self-discovery | New agents operational in minutes |
| Human Oversight | Mandatory compliance workflow with managing partner sign-off | Nothing publishes without human authorization |
| Communication | 31-channel Slack integration via mesh-bridge | Agent participates in all channels, routes with citations |
| Research | Deep research pipeline across 4 source types | Web + KB + government data + transcripts, all cited |
| Operations | SOP database with org chart integration | Structured records with role-based routing |
Unit economics: $250/month replaces approximately $15,000/month in SaaS subscriptions (Airtable, Zapier, Notion, scattered AI tools) and 3–5 FTEs of operational work.
2.2 What This Proves
The PE Fund AI OS validates three architectural claims:
Self-describing systems work. The mesh's REST API is the discovery mechanism. New agents connect, query available endpoints, and self-configure. The system describes itself through its API.
Human-in-the-loop is a scaling strategy. METR's randomized controlled trial found developers were 19% slower with AI tools while believing they were 20% faster — a 39-percentage-point perception gap. Mandatory human review catches the errors that AI confidence obscures.
Agent tools beat agent autonomy for ROI. The value is not that agents operate independently. The value is that a five-person team operates with the throughput of a fifteen-person team because their tools are orchestrated, discoverable, and scoped.
Part 3: The Creation Pipeline (singularity-engine)
3.1 What It Is
The singularity-engine is a separate OSS project — an autonomous application generation pipeline: natural language input → working deployed software → live URL. It operates standalone today with planned mesh integration.
3.2 Current Architecture (v0.1 — Standalone)
┌───────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────────┐
│ Trigger │────►│ Generation │────►│ Deployment │────►│ Delivery │
│ │ │ │ │ │ │ │
│ Tweet / │ │ Claude API │ │ GitHub │ │ Reply │
│ API call │ │ Code gen │ │ Pages │ │ with │
│ Natural │ │ HTML/CSS/JS │ │ Static │ │ live URL │
│ language │ │ ~60 seconds │ │ hosting │ │ │
└───────────┘ └──────────────┘ └──────────────┘ └───────────┘
Infrastructure: AWS Lambda, DynamoDB, GitHub Pages
Cost: ~$0.10 per generation
License: MIT
3.3 Mesh-Aware Architecture (Planned)
When singularity-engine operates within a mesh, it would gain:
- Context assembly: Querying mesh knowledge bases via API for domain context
- Identity verification: Validating the requestor's mesh role and permissions
- Governance: All outputs subject to mesh RBAC and audit trails
This integration is planned but not yet built.
Part 4: Build Phases
What's Built vs. What's Planned
| Component | Status | Details |
|---|---|---|
| Go server (Chi router) | Live | Single binary, production-ready |
| 296 REST API handlers | Live | Full mesh CRUD, bots, rooms, messages |
| 25 SQLite database tables | Live | Meshes, rooms, messages, members, bots, files, apps |
| 7-role RBAC | Live | Enforced on every API handler |
| WebSocket + Socket.IO | Live | Real-time events, presence, typing |
| Docker bot spawning | Live | Containerized agent deployment |
| Bot SDK (Go) | Live | Event-driven bot development |
| mesh-bridge CLI | Live | Slack bridging, extensible |
| File system | Live | Uploads, attachments, per-room storage |
| Inline apps | Live | Embedded application framework |
| UCAN/DID identity | Experimental | Behind feature flags |
| Federation (HTTP relay) | Experimental | Cross-mesh peering, early-stage |
| Graduated autonomy | Planned | Trust scoring, permission graduation |
| Cross-mesh commerce | Planned | Federated agent transactions |
| Token economic layer | Planned | Trust bonds, staking, coordination fees |
| singularity-engine integration | Planned | Mesh-aware code generation |
Build Phases
Phase 1: The Server (Complete)
The Go server is built and operational. 296 API handlers, 25 database tables, RBAC, WebSocket real-time, Docker bot spawning, Bot SDK, mesh-bridge CLI.
This is a compelling standalone product. A self-hosted agent coordination server with full RBAC, real-time communication, and containerized bot deployment. Deploy it, run bots, coordinate work.
Phase 2: Federation (In Progress)
Ship production-grade federation.
| What Ships | What It Enables |
|---|---|
| HTTP relay federation (hardened) | Mesh instances discover and communicate with each other |
| UCAN/DID (out of feature flags) | Cryptographic identity and capability delegation across meshes |
| Cross-mesh messaging | Agents and humans communicating across organizational boundaries |
| Federation admin UI | Managing peers, monitoring cross-mesh traffic |
This is where The Mesh becomes a network. Two mesh instances can discover each other, exchange messages, and verify identity — all without a central server.
Phase 3: Advanced Features (Planned)
| What Ships | What It Enables |
|---|---|
| Graduated autonomy | Bots earning broader permissions through demonstrated reliability |
| Trust scoring | Behavioral metrics informing permission decisions |
| Token economic layer | $MESH integration for trust bonds, staking, coordination fees |
| Advanced federation | More sophisticated peer discovery and routing |
This is where the economic layer activates. But only after federation proves itself in production.
Technology Stack
| Layer | Technology | Status |
|---|---|---|
| Server | Go (Chi router) | Production |
| Storage | SQLite | Production |
| Real-time | WebSocket + Socket.IO | Production |
| Bot spawning | Docker / Kubernetes | Production |
| Bot development | Bot SDK (Go package) | Production |
| External bridges | mesh-bridge CLI | Production |
| Identity (local) | RBAC (7 roles) | Production |
| Identity (federated) | W3C DIDs | Experimental |
| Permissions (federated) | UCAN v1 | Experimental |
| Federation | HTTP relay | Experimental |
| Token | $MESH on BASE | Exists (not integrated) |
Primary technical risk: Federation hardening. The Go server, RBAC, bot spawning, and real-time communication are production-ready. The challenge is making federation reliable, secure, and performant at scale — particularly identity verification and capability delegation across trust boundaries.
What's Needed
A co-founder with go-to-market, enterprise sales, or developer relations experience. The server is built. The commercial strategy, developer community, and enterprise adoption path need a dedicated leader.
Distributed systems engineers experienced in federation protocols, real-time networking, or security. The Go server is solid. Federation hardening and UCAN/DID production-readiness require deep expertise.
Bot developers who want to build on the Bot SDK, create mesh-bridge integrations, and push the agent coordination model. The ecosystem grows through community contributions.
Early adopters willing to run mesh instances and stress-test federation. The server is ready for single-instance production use. Multi-mesh federation needs real-world testing.
The Mesh — GitHub: github.com/Metatransformer/the-mesh
Follow on X: @metatransformr
Discord: discord.gg/CYp4wJvFQF
Prepared by Nick Bryant @metatransformr × Claude Opus 4.6 | Metatransformer LLC Article 5 of 5: Technical Architecture