Dev VPS

Develop Matrix OS on a user or developer VPS. Review the runtime layout, development workflow, and verification steps before changing a hosted computer.

Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.

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.

Recommended workflow

Terminal

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.

What lives on the VPS

Recommended workflow

Development rules

Related

On this page