Developer Overview
Technical reference for building on and contributing to Matrix OS.
This section covers the technical internals of Matrix OS for developers who want to understand the architecture, contribute to the project, build apps, or extend the system.
AI-generated documentation
For a comprehensive, always-up-to-date reference generated from the source code, see the Matrix OS DeepWiki.
Tech Stack
| Layer | Technology |
|---|---|
| Language | TypeScript 5.5+ (strict mode, ES modules) |
| Runtime | Node.js 24+ |
| AI | Claude Agent SDK V1 (query() + resume) with Opus 4.6 |
| Frontend | Next.js 16, React 19 |
| Backend | Hono (platform control plane + customer gateway) |
| Channels | node-telegram-bot-api, @whiskeysockets/baileys, discord.js, @slack/bolt |
| Federation | Matrix protocol (matrix-js-sdk) |
| Database | PostgreSQL via Kysely for platform and customer-local app/workspace data |
| Validation | Zod 4 (zod/v4 import) |
| Scheduling | node-cron + native timers |
| Testing | Vitest (99-100% coverage target, @vitest/coverage-v8) |
| Package Manager | pnpm (install), bun (scripts) |
Key Concepts
Kernel = Agent SDK
The spawnKernel() function in packages/kernel/src/spawn.ts is the entry point. It calls query() for initial prompts and resume for multi-turn conversations. The kernelOptions() function in packages/kernel/src/options.ts configures the kernel with the system prompt, IPC servers, agent definitions, and hooks.
Platform + Customer VPS Runtime
Production Matrix OS has a shared platform control plane and one customer VPS per active user. The platform owns Clerk auth, routing, provisioning, integrations, and host-bundle publication. The customer VPS runs the user's gateway, shell, code editor, apps, local Postgres, sync, and backups.
Apps = Vite + React By Default
First-party and polished apps should be Vite + React projects with runtime: "vite" and build.output: "dist" in matrix.json. Apps that need structured data declare storage.tables; the gateway creates schema-per-app Postgres tables and exposes access through /api/bridge/query.
App processes should not receive raw DATABASE_URL. The bridge API is the intended scoped route into the user's local Postgres database.
IPC via MCP
The kernel communicates with the system through 26 IPC tools exposed as an in-process MCP server via createSdkMcpServer(). Each tool is defined with tool(), a Zod schema for input validation, and an async handler.
Hooks
Hooks intercept agent actions at defined lifecycle points. PreToolUse hooks run before tool execution (safety guards, protected files). PostToolUse hooks run after (git snapshots, state updates, shell notifications). A Stop hook persists the session.
Dispatch Queue
The gateway's dispatcher manages a serial FIFO queue by default, ensuring only one kernel call runs at a time to prevent file system corruption. It can be configured for concurrent dispatch with maxConcurrency, where each process registers in the PostgreSQL tasks table.
Developer Resources
Architecture
Detailed system architecture: kernel, gateway, dispatcher, request flow.
IPC Tools & Hooks
All 26 IPC tools, the hook lifecycle, and the permission model.
Skills System
Skill validation, caching, composable skills, and build pipeline optimization.
Logging & Usage
Kernel logging, token tracking, usage API, file audit trail.
Testing
TDD approach, running tests, coverage targets, and test structure.
Contributing
Setup, development rules, commit conventions, and spec-driven development.
DeepWiki
AI-generated documentation from the Matrix OS source code.
How is this guide?