Technical Details

Under the hood

Matrix OS treats an LLM as a literal operating system kernel. This page covers the architecture, design decisions, heritage, and the computing paradigm we call Web 4.

April 202615 min readSource

The core idea

An LLM as a literal operating system

This is not a metaphor for marketing. Every concept in traditional OS design maps directly to a component in Matrix OS. The LLM is the CPU. The context window is RAM. Files are files.

Traditional OS

Matrix OS

Role

CPU

Claude Opus 4.6

Reasoning engine that executes all instructions

RAM

Context window (1M tokens)

Working memory for the current task

Kernel

Agent SDK + system prompt

Core loop that dispatches tools and sub-agents

Processes

Sub-agents

Isolated workers with their own context windows

Disk

File system (~/)

Persistent storage -- apps, data, config, identity

System calls

MCP tools

Typed interfaces the kernel exposes to user space

Device drivers

Channel adapters

Telegram, WhatsApp, Discord, Slack, Voice, Web

IPC

Tool results + file watches

How the kernel and shells communicate

BIOS / Firmware

SOUL (soul.md)

Identity, personality, behavioral constraints

Shell

Web desktop / chat / CLI

Multiple renderers, same kernel underneath

Architecture

Gateway → Kernel → Files

Gateway (Hono)

—HTTP + WebSocket server
—Channel adapters (Telegram, WhatsApp, Discord, Slack)
—Voice pipeline (STT/TTS)
—Auth, rate limiting, body limits
—Routes everything to the kernel

Kernel (Agent SDK)

—Claude Opus 4.6 with 1M context
—MCP tools for file I/O, shell, apps
—Sub-agent spawning for heavy tasks
—Session resume for multi-turn conversations
—SOUL identity injected at cache level

File System (~/)

—Apps in ~/apps/ (HTML, codebases)
—Data in ~/data/ (SQLite, JSON)
—Agents in ~/agents/ (markdown definitions)
—Config in ~/system/ (JSON files)
—Git-versioned, peer-to-peer sync

Voice    ──┐
Telegram ──┤
WhatsApp ──┤
Discord  ──┼──► Gateway ──► Dispatcher ──► Kernel ──► File Mutations
Slack    ──┤                                             │
Web Chat ──┤                                             ▼
REST API ──┘                                     Shell watches ~/
                                                 UI updates in real-time

Constitution

Seven design principles

Everything Is a FileNON-NEGOTIABLE

Every piece of state is a file on disk. Apps, config, identity, agent definitions, user data. Backup = copy a folder. Share = send a file. No opaque databases for core state.

Agent Is the Kernel

The Claude Agent SDK is not bolted on -- it IS the kernel. Full machine control: file system, shell, processes, network. Every user interaction flows through the agent.

III

Headless Core, Multi-Shell

The core works without any UI. The web desktop is one renderer. Telegram, WhatsApp, Discord, Slack are additional shells. CLI, mobile, voice-only, API -- all read the same files.

Self-Healing & Self-Expanding

The OS detects failures, diagnoses root causes, and patches itself. It creates new capabilities by writing new agent files and tools. Git snapshots before every mutation.

Simplicity Over Sophistication

Single-process async before worker threads. File-based IPC before message queues. SQLite before Postgres. HTML apps before full-stack frameworks. Escalate only when the simpler approach fails.

Defense in DepthNON-NEGOTIABLE

Auth matrix, input validation, resource limits, timeouts on every external call, constant-time secret comparison, atomic file writes. Security is part of the spec, not a follow-up.

VII

Test-Driven DevelopmentNON-NEGOTIABLE

Failing tests first, then implement. 99-100% coverage target. Spike before spec. Integration tests against real SDK behavior, not just docs. 2,800+ tests and counting.

Heritage

Built on OpenClaw's shoulders

OpenClaw proved that a personal AI agent -- reachable from any chat platform, with persistent memory and full system access -- changes how people use computers. Matrix OS takes that foundation and adds a generative layer: the agent doesn't just orchestrate tools, it creates new software in real-time.

Pattern

OpenClaw

Matrix OS

Gateway

Routes chat messages from channels to agent, response back to channel

Routes input to kernel, output is file mutations. Shell watches filesystem for changes.

Skills

YAML + Markdown files compiled into system prompt. Guide the agent, don't execute.

Same pattern, but skills can also trigger sub-agents and file generation.

Sessions

In-memory conversation state per channel/user

Agent SDK resume tokens + file-based session state. Survives restarts.

Output

Send message back to originating channel

Write files to disk. Every action = file created, modified, or deleted.

Channels

Telegram, Discord, Slack, iMessage, Web -- all first-class

Same channels, plus Voice as primary gateway. Matrix protocol for federation.

Extensibility

Plugin SDK with hooks, tool registration, config injection

Two-tier: file-based (write a markdown skill) + code-based (MCP tools).

What we took

Gateway pattern, skills-as-docs, channel adapters, single-agent routing, tool system with typed schemas, hooks at boundaries.

What we simplified

No multi-tenant design, no platform-specific code paths, lighter dependency tree, file-based config over environment variables.

What we invented

Generative apps (software from conversation), file-as-output, OS metaphor (LLM = CPU), self-healing kernel, peer-to-peer git sync, Web 4.

The bigger picture

Web 4: the unification

Every era of computing unified previously separate things. Web 4 unifies your OS, messaging, social media, AI, apps, games, and identity into one platform.

Web 1

Static pages. Information published, consumed passively.

Web 2

Platforms. Social, messaging, apps -- all siloed. Identity scattered.

Web 3

Decentralization. Crypto, wallets. Promised ownership, delivered complexity.

Web 4

Unification. One AI, one identity, one file system, every device.

Matrix Protocol foundation

—Federated identity: @user:matrix-os.com
—Server-to-server federation with the broader Matrix ecosystem
—End-to-end encryption (Olm/Megolm) for all communication
—AI-to-AI protocol via custom Matrix event types
—Any Matrix client (Element, FluffyChat) can talk to Matrix OS

Peer-to-peer sync

—Every device runs its own Matrix OS instance
—Home directory (~/) is a git repo
—Devices sync via git push/pull -- no central server required
—Cloud instance is just another peer (always-on)
—Conflict resolution is AI-assisted: kernel reads git markers and merges

Stack

What it's built with

RuntimeNode.js 24+, TypeScript 5.5+ (strict), ES modules

AIClaude Agent SDK V1 query() + resume, Opus 4.6, 1M context

FrontendNext.js 16, React 19, Turbopack, React Compiler

BackendHono (HTTP, WebSocket, channel adapters)

DatabaseSQLite / Drizzle ORM (kernel), Postgres / Kysely (social)

ValidationZod 4 (schemas, tool params, API contracts)

TestingVitest, @vitest/coverage-v8, TDD workflow

ProtocolMatrix (federation, E2E encryption, identity)

ChannelsTelegram, WhatsApp (Baileys), Discord.js, Slack Bolt, Voice

InfraDocker, OrbStack, Hetzner VPS, pnpm + bun

By the numbers

Built in public, tested obsessively

2,800+

Tests passing

100K+

Lines of TypeScript

214

Test files

Packages

46+

Completed phases

Channels

Want to go deeper?

Read the whitepaper View source Documentation