Matrix OSMatrix OS

Dev VPS

Develop Matrix OS inside a user or developer VPS.

The dev VPS workflow treats a Matrix computer as the development machine. This is the same shape as production customer runtime: a user-owned home directory, local services, shell sessions, previews, and agent CLIs.

What lives on the VPS

  • Source repositories under ~/projects.
  • Runtime state and owner files under the Matrix home.
  • Terminal sessions backed by zellij.
  • Shell, gateway, code-server, sync, and agent CLIs from the host bundle.
  • A local owner-controlled Postgres endpoint for app/workspace data.
matrix login
matrix shell connect -c dev
matrix run -it --session dev -- gh auth login
matrix run -it --session dev -- codex

Clone work into ~/projects, run dev servers inside Matrix, and expose previews through the Matrix-authenticated routes instead of ad hoc public tunnels when possible.

Development rules

  • Keep platform-owned secrets on the platform. Do not copy Pipedream, Clerk, Gmail, GitHub, Slack, or provider secrets into customer VPS env files.
  • Use Matrix gateway/platform APIs for authenticated integration actions.
  • Prefer named sessions so the web shell, CLI, and agents can reattach predictably.
  • If zellij session creation fails, run matrix shell ls and connect to an existing session instead of retrying blindly.

Production runtime is VPS-native

Customer-facing Matrix OS does not ship through Docker Compose or rolling container restarts. Shell/gateway changes for existing customers need a host-bundle rebuild, publish, and VPS refresh.

How is this guide?

Contributor Overview

Technical reference for building on, operating, and contributing to Matrix OS.

Agent Matrix Skills

Canonical Matrix skill pack for supported coding agents.

On this page

What lives on the VPS
Recommended workflow
Development rules
Related