Matrix OS gives you a hosted cloud computer: browser desktop, files, terminal sessions, apps, integrations, messages, and AI agents running on your personal VPS. Open any browser, sign in, and your workspace is there. Install the Matrix CLI and Claude, Codex, GitHub CLI, or Hermes can attach to the same machine.
It is not a chat box beside your software. The AI is the kernel. The shell, gateway, files, apps, terminal, channels, and agents are one operating environment.
Why Matrix OS
Most AI products leave your work scattered across chats, terminals, dashboards, and local machines. Matrix OS gives agents a persistent place to work.
| You need | Matrix OS gives you |
|---|
| A real workspace for AI agents | A hosted personal VPS with browser shell, terminal sessions, files, apps, and logs |
| Software without waiting on a SaaS roadmap | Apps generated from natural language and saved as inspectable projects |
| Continuity across devices | One cloud desktop reachable from the web, Matrix CLI, and messaging channels |
| Data you can leave with | Owner-controlled files plus Postgres for durable app and workspace data |
| A system that can improve itself | Agents, skills, hooks, cron jobs, and self-healing workflows |
Matrix OS is the foundation for Web 4: a unified environment where operating system, messaging, social identity, apps, games, files, and AI agents are one system.
Install Matrix OS
Managed Matrix Cloud
Start at the landing page: matrix-os.com.
Sign up or log in from there, choose a Matrix handle, provision your private runtime, and open the browser desktop. Managed Matrix OS uses a platform control plane plus one VPS-native runtime per active user. Matrix manages routing, auth, updates, backups, billing, and integrations. Your VPS is where your files, terminal sessions, generated apps, integrations, and coding agents live.
Manual VPS Install
Run Matrix OS on an existing Linux VPS you control:
curl -fsSL https://matrix-os.com/install-server.sh | sudo bash
The manual installer downloads a verified host bundle, creates the matrix user, starts local Postgres, the Matrix gateway, web shell, code-server, nginx, and optional coding-agent tools under systemd. A domain is optional: by default nginx answers on the server IP address with Basic Auth. Manual VPS operators own DNS, TLS, backups, updates, integrations, and server security. See Self-host docs for prerequisites, telemetry, and tradeoffs.
Matrix CLI
Install the CLI:
# macOS or Linux with Homebrew
brew install finnaai/tap/matrix
# Or with npm
npm install -g @finnaai/matrix
# Or with the install script
curl -fsSL https://get.matrix-os.com | sh
Log in from the CLI and inspect your instance:
matrix login
matrix whoami
matrix status
matrix instance info
matrix login opens a browser/device flow against the hosted Matrix cloud. If it says no Matrix instance exists yet, sign up at matrix-os.com, finish provisioning, then run matrix login again.
Agent Setup
Agents should read the public skill file and follow it:
https://matrix-os.com/skills.md
Install the skill locally if your agent runtime supports file skills:
npx skills add HamedMP/matrix-os --skill matrix-os
Then use project-scoped Matrix terminal tabs for remote work:
# Bring your own terminal agent.
matrix run -it -- claude
matrix run -it -- codex
# Outside a known project, interactive commands use the reserved main workspace.
matrix run -it --project main -- gh auth login
matrix shell list
matrix shell connect --project main --tab <tab-id>
Detach from an interactive tab with Ctrl-\ Ctrl-\. The remote process stays alive and can be reattached from the Matrix web terminal or CLI. This is the same computer the hosted browser shell shows.
From Source
Use the source install when contributing to Matrix OS itself:
git clone https://github.com/HamedMP/matrix-os.git
cd matrix-os
flox activate
bun run dev # source/HMR: gateway + proxy + shell
Without Flox, install Node.js 24+, pnpm 10, and bun, then run:
pnpm install
bun run dev
Development services:
bun run dev:gateway # Hono gateway
bun run dev:shell # Next.js shell
bun run dev:proxy # Shared API proxy
bun run dev:platform # Multi-tenant platform
The source command does not start PostgreSQL, MinIO, or platform.
Use bun run docker:full for that complete topology, or
bun run docker:full:smoke for a bounded full-stack health check with cleanup.
See Developer Onboarding for environment files,
prerequisites, URLs, and health checks.
What It Can Do
Demo
Built for the Anthropic "Built with Opus 4.6" Hackathon in February 2026, where Matrix OS placed in the top 20.
Architecture
Web shell / CLI / Telegram / WhatsApp / Discord / Slack / Matrix / Voice
|
v
Hono Gateway + WebSocket bus
REST, terminal, files, messages, apps, cron, metrics
|
v
Dispatcher -> AI Kernel (Claude Agent SDK V1)
|
Builder / Researcher / Deployer / Healer / Evolver agents
|
v
Owner-controlled files + Postgres + generated apps + integrations
The OS metaphor is literal:
| Computer concept | Matrix OS equivalent |
|---|
| CPU | Frontier model routing, currently Claude Opus 4.6 |
| Kernel | Main Agent SDK V1 query() loop with resume |
| Processes | Specialized sub-agents with isolated context |
| Disk | Matrix home files plus owner-controlled Postgres |
| System calls | MCP and gateway IPC tools |
| Drivers | Channel adapters, integrations, browser, terminal, voice |
| Shell | Next.js desktop/canvas UI, CLI, and messaging surfaces |
Tech Stack
| Layer | Technology |
|---|
| Language | TypeScript 5.5+ strict, ES modules |
| Runtime | Node.js 24+ |
| AI | Claude Agent SDK V1 query() + resume, Opus 4.6 |
| Frontend | Next.js 16, React 19, Turbopack, React Compiler |
| Backend | Hono HTTP/WebSocket gateway |
| Database | PostgreSQL via Kysely |
| Validation | Zod 4 via zod/v4 |
| Terminal | node-pty, xterm.js, WebGL renderer |
| Integrations | Pipedream Connect |
| Observability | Prometheus metrics |
| Testing | Vitest, @vitest/coverage-v8 |
| Package manager | pnpm for install, bun for scripts |
Repository Map
packages/kernel/ AI kernel, agents, hooks, SOUL, skills
packages/gateway/ Hono HTTP/WS gateway, channels, cron, terminal, voice
packages/platform/ Hosted control plane, auth, provisioning, routing
packages/proxy/ Shared API proxy and usage tracking
packages/ui/ Shared UI components
shell/ Next.js desktop and canvas shell
home/ Matrix home template copied on first boot
specs/ Architecture and feature specs
tests/ Vitest suites
docs/ Developer and operations docs
The public website and docs are maintained separately in the private
FinnaAI/matrix-os-site repository.
Development
Run the core checks before opening a PR:
bun run typecheck
bun run check:patterns
bun run test
Other useful commands:
bun run test:watch
bun run test:integration
bun run test:coverage
bun run test:e2e
Docker commands are available for local legacy development, but production Matrix OS is VPS-native per user. Customer runtime updates ship as host bundles, not rolling Docker image restarts.
Current Status
Matrix OS is live at matrix-os.com, with hosted runtime provisioning, a canvas-first shell, file browser, terminal, generated apps, onboarding, integrations, observability, docs, and the early Web 4 foundation in place.
Current focus areas:
- Paid beta readiness and production polish
- Canvas workspace and cloud coding workflows
- Mobile shell
- Matrix messaging bridge for Telegram and WhatsApp
- SDK-native skills and agent-readable setup
See:
Community
Star History
License
AGPL-3.0
Matrix OS. Software that does not exist until you need it. Once it does, it is yours.
