Getting Started

Prerequisites

Node.js 24+ -- check with node --version

pnpm -- enable via corepack:

corepack enable && corepack prepare pnpm@latest --activate

Anthropic API key -- get one at console.anthropic.com

Node.js version

Matrix OS requires Node.js 24 or later. The bin/matrixos.ts doctor command verifies your environment automatically.

Installation

Clone and install

git clone https://github.com/hamedmp/matrix-os.git
cd matrix-os
pnpm install

Set your API key

export ANTHROPIC_API_KEY=sk-ant-...

Start the OS

bun run dev

This starts two servers concurrently:

Gateway at http://localhost:4000 -- the Hono backend (kernel, channels, file server, WebSocket)
Shell at http://localhost:3000 -- the Next.js web desktop

On first boot, the gateway copies the home/ template to ~/matrixos/, initializes git, and sets up default agents, skills, config, and SOUL identity.

Running Servers Individually

bun run dev:gateway   # Gateway only (http://localhost:4000)
bun run dev:shell     # Shell only (http://localhost:3000)

Your First Conversation

Open http://localhost:3000 in your browser. You'll see the Matrix OS desktop with a chat panel, dock, and input bar.

Type something like:

Build me an expense tracker with categories

Here's what happens:

Your message hits the gateway's /ws WebSocket endpoint
The dispatcher adds it to the serial queue and creates a task in SQLite
spawnKernel() builds a system prompt with SOUL, identity, skills TOC, and active processes
The kernel invokes Claude Agent SDK query() and selects the Builder agent
Builder uses IPC tools to create files in ~/matrixos/apps/
gitSnapshotHook commits the changes automatically
The file watcher detects new files and the shell renders the app in an AppViewer window
Response tokens stream back to the chat panel in real time

Everything it creates is a file you own. Check ~/matrixos/apps/ to see the generated code.

Project Structure

packages/kernel/     # AI kernel (Agent SDK, agents, IPC, hooks, SOUL, skills)
packages/gateway/    # Hono HTTP/WebSocket gateway + channels + cron + heartbeat
packages/platform/   # Multi-tenant orchestrator (Hono :9000, Drizzle, dockerode)
shell/               # Next.js 16 web desktop (one of many shells)
www/                 # matrix-os.com website (you're reading its docs)
home/                # File system template (copied on first boot)
tests/               # Vitest test suites (993+ tests)
specs/               # Architecture specifications
distro/              # Docker, cloudflared, systemd configs

Running Tests

bun run test              # Unit tests (~993 tests, ~11s)
bun run test:watch        # Watch mode
bun run test:coverage     # With coverage report
bun run test:integration  # Integration tests (needs API key, uses haiku)

Environment Variables

Variable	Default	Description
`ANTHROPIC_API_KEY`	--	Required for kernel AI features
`MATRIX_HOME`	`~/matrixos/`	Home directory path
`MATRIX_AUTH_TOKEN`	--	Bearer token for web shell auth (cloud deployments)
`PORT`	`4000`	Gateway port
`NEXT_PUBLIC_GATEWAY_WS`	`ws://localhost:4000/ws`	Shell WebSocket URL
`NEXT_PUBLIC_GATEWAY_URL`	`http://localhost:4000`	Shell HTTP URL
`GATEWAY_URL`	`http://localhost:4000`	Next.js proxy target

Channel tokens (Telegram, Discord, Slack, WhatsApp) are configured in ~/matrixos/system/config.json -- everything is a file.

Next Steps

Explore the Agent System to understand the five core agents
Read about the File System to understand ~/matrixos/
Connect a Channel like Telegram or Discord

Getting Started

On this page