OpenJaws — Cell Mesh Platform

OpenJaws is the primary implementation of the Cell Mesh architecture: a global, sovereign, distributed computing model where every piece of software is a self-contained, self-healing, type-safe cell.

The goal is to make monorepos obsolete and replace them with something better — a mesh of independent, composable cells that scale to infinity, self-replicate across infrastructure, and expose 100% type-safe APIs to everything that needs them.

---

The Core Idea

Traditional backend development forces you to either:

• Build a monorepo — coupled releases, shared blast radius, tooling bureaucracy
• Build microservices — operational complexity, no shared types, bespoke service mesh

Cells are a third option. Each cell is a sovereign unit that:

• Runs its own process, manages its own dependencies, deploys independently
• Discovers other cells automatically through a shared registry
• Exposes typed capabilities that callers use without knowing the implementation
• Self-replicates when spawned on new nodes via Cell.toml

bun run orchestrator-cell/index.ts

One command. The orchestrator reads every Cell.toml in the directory tree, spawns each cell, and the mesh self-assembles. Add a new cell directory with a Cell.toml — it appears in the mesh. Remove it — the mesh heals around the gap.

---

Quick Start

# 1. Clone
git clone https://github.com/Leif-Rydenfalk/openjaws.git
cd openjaws

# 2. Link the protocol
cd protocols/cell-mesh-protocol-1
bun install && bun link
cd ../../mesh1

# 3. Start the mesh
cd orchestrator-cell
bun install && bun run index.ts

The orchestrator will discover all cells in mesh1/ via their Cell.toml files and spawn them.

---

Repository Layout

openjaws/
├── mesh1/                      # The primary mesh instance
│   ├── orchestrator-cell/      # Spawns and supervises all cells
│   ├── registry-cell/          # Shared capability registry
│   ├── ai/                     # AI inference cell (Claude)
│   ├── supabase-cell/          # Supabase management cell
│   ├── docker-cell/            # Docker management cell
│   ├── hetzner-cell/           # Hetzner cloud provisioning
│   ├── lighthouse-launcher/    # One-click node provisioning + GitOps
│   ├── genesis-igniter-cell/   # Bootstrap new mesh nodes
│   ├── mobile-bridge/          # PWA dashboard for mobile mesh control
│   ├── global-command-center/  # Mesh-wide control panel
│   ├── telemetry/              # Metrics and observability
│   ├── telegram/               # Telegram bot interface
│   └── apps/                   # Application cells
│       ├── trading/            # Live trading cell (Rust)
│       ├── prediction/         # Market prediction cell
│       ├── checklist/          # Example task cell
│       ├── ai-ui/              # AI chat interface
│       ├── codegen/            # Type-safe mesh codegen
│       ├── skills/             # Capability search index
│       └── ...
└── protocols/
    └── cell-mesh-protocol-1/   # The protocol SDK (TypeScript + Rust)

---

What a Cell Is

A cell is the smallest deployable unit. It is:

1. A process — runs independently, crashes independently, restarts independently
2. A capability provider — exposes named, typed operations to the mesh
3. A mesh participant — discovers and calls other cells through the shared atlas
4. Declared by Cell.toml — the orchestrator reads this to know how to spawn it

Minimal cell:

// mesh1/my-cell/index.ts
import { TypedRheoCell, router, procedure, z } from "cell-mesh-protocol-1";

const cell = new TypedRheoCell("my-cell", 0);

const myRouter = router({
    myCell: router({
        greet: procedure
            .input(z.object({ name: z.string() }))
            .output(z.object({ message: z.string() }))
            .query(async ({ name }) => ({ message: `Hello, ${name}!` }))
    })
});

cell.useRouter(myRouter);
await cell.listen();

# mesh1/my-cell/Cell.toml
id = "my-cell"
command = "bun install && bun run index.ts"
critical = false
scalable = false

Any other cell in the mesh can now call my-cell/greet with full type safety. No service discovery config. No API gateway. No OpenAPI spec to maintain.

---

Cell.toml Reference

id = "cell-name"                          # Unique identifier in the mesh
command = "bun install && bun run index.ts"  # How to start the cell
critical = false                          # If true, orchestrator restarts on crash
scalable = false                          # Future: enables multi-instance scaling

[env]
PORT = "5000"                             # Environment vars injected at spawn time
SOME_SECRET = "..."

---

Type-Safe Mesh Calls

Calling another cell looks like calling a local function:

// From any cell
const result = await cell.mesh.myCell.greet({ name: "world" });
// result.message is typed as string — no casting, no runtime surprises

Types flow from the router definition through the mesh automatically. The codegen cell generates a global mesh-types.d.ts that gives IDE completions across all cells.

---

Infrastructure Cells

Orchestrator

Scans the mesh1/ tree for Cell.toml files, spawns each cell as a subprocess, and monitors health. The only cell that isn't declared by a Cell.toml — it is the root of the mesh.

Lighthouse Launcher

Provisions Hetzner Cloud servers, clones the repo, links the protocol, and starts the orchestrator via systemd. Includes a 1-minute Git auto-updater cron job — push to main, all nodes update within a minute.

Genesis Igniter

A web UI for bootstrapping a fresh mesh node from scratch. Handles the first-run ceremony: configure cloud tokens, launch apex node, watch it come online.

Mobile Bridge

A PWA cell that exposes the entire mesh as a mobile-friendly dashboard. File browsing, cell management, registry inspection — all from a phone.

---

Self-Healing and Scaling

Cells with critical = true are automatically restarted by the orchestrator if they crash. The mesh continues routing around dead cells until they recover.

Scaling works by identity: a cell with scalable = true can run multiple instances. Each instance registers with a unique address; the mesh load-balances across them automatically.

Global deployment: the lighthouse-launcher cell can provision a new node anywhere in the world, install the full mesh, and have it join the atlas within minutes. The new node's cells are indistinguishable from local cells.

---

Roadmap

Now — Core Mesh

• TypeScript and Rust cell implementations
• Automatic cell discovery and gossip-based atlas
• Type-safe cross-cell RPC via router / procedure / z
• Orchestrator-based spawn and health management
• GitOps deployment via Hetzner + systemd

Near Term

Auth Cell — The mesh security model. A single auth cell acts as the only publicly-exposed entry point. All inbound requests pass through it; only authenticated requests are forwarded to internal cells. The auth cell is the membrane of the mesh.

Frontend SDK — cell-mesh-react: a React package that gives browser apps a useCell hook and typed mesh client. No REST, no GraphQL, no boilerplate — just call mesh capabilities directly from components.

SvelteKit Integration — cell-mesh-svelte: server-side mesh participation via hooks, client-side via browser cell shim.

Cell Registry — A public registry for shareable cells. Publish a supabase-cell, stripe-cell, sendgrid-cell once; anyone adds it to their mesh by referencing it in Cell.toml.

Future

Mesh Federation — Meshes composing into super-meshes. An enterprise mesh can consume capabilities from a partner mesh through a federation gateway, with the same type-safe interface.

WASM Cells — Cells compiled to WebAssembly, deployable in browsers, edge runtimes, and embedded systems. The same cell protocol, running everywhere.

Protocol Versioning — Cells declare which protocol version they implement. The mesh gateway translates between versions, enabling gradual upgrades without coordinated migrations.

Visual Mesh Editor — A drag-and-drop interface for composing meshes. Wire cells together visually; the editor generates Cell.toml files and connection configs.

---

Global Registries

The mesh has two protocols that together give you a global view of what cells exist as source and what is running right now:

• protocols/cell-registry-protocol-1 — catalog of every cell repo. Source: cells.json.
• protocols/active-instances-protocol-1 — discovery of running nodes via a lighthouse + a small JSON catalog of lighthouses. Source: lighthouses.json.

How they fit together: docs/global-mesh-view.md.

Every repo using cell-mesh-protocol-1 MUST include cell-mesh-protocol-1 in its name (e.g. cell-mesh-protocol-1-supabase-cell) — see CLAUDE.md.

---

Code Standards

See protocols/cell-mesh-protocol-1/README.md for the full protocol spec and coding standards.

Key rules:

• Every cell uses TypedRheoCell with a router — never raw capability strings in production cells
• Schemas use the built-in z validator — same shape as Zod, no extra dependency
• Cell IDs are kebab-case: my-cell, not MyCell or my_cell
• Capability paths mirror the router structure: router({ myCell: router({ greet: ... }) }) → my-cell/greet
• Cell.toml lives at the root of the cell directory, never nested
• critical = true only for cells the mesh cannot function without (registry, auth)
• No cell imports another cell's source — capabilities only, never source-level coupling