Storage

Matrix OS keeps your workspace durable and recoverable without asking you to manage infrastructure.

Your Matrix environment has two main kinds of state:

• Files: apps, documents, settings, agent instructions, exports, icons, and project files.
• Database records: app tables, canvas documents, social data, task data, and structured workspace state.

Where Your Data Lives

In production, each active user gets a customer VPS. That VPS has:

• your Matrix home at /home/matrix/home;
• your apps under /home/matrix/home/apps;
• your system files under /home/matrix/home/system;
• a local Postgres database endpoint at 127.0.0.1:5432;
• backup and recovery scripts that upload database snapshots and metadata to R2.

The platform keeps control-plane data such as authentication, routing, provisioning status, and integration metadata. Your personal app and workspace data is stored in your Matrix environment.

What Uses Files

Files are used for:

• app source and built app assets;
• settings and preferences;
• icons, images, documents, and exports;
• agent instructions and skills;
• project files and workspace material;
• recovery artifacts and snapshots.

You can ask Matrix to find, summarize, organize, rename, export, or transform files for you.

What Uses Postgres

Postgres is used for data that needs structure:

• app records such as notes, tasks, expenses, leads, habits, and saved items;
• workspace canvas documents and references;
• social and collaboration state;
• app registry metadata;
• key-value app state migrated from older file storage.

Apps do not need to handle database credentials directly. Matrix's gateway connects to the local Postgres database and exposes scoped app access through /api/bridge/query.

App Data

When Matrix builds or installs an app with structured storage, the app declares tables in matrix.json. The gateway creates those tables in the user's local Postgres database using a schema-per-app model.

For example, a task app can declare a tasks table. The app then uses the Matrix bridge to create, list, update, and delete tasks. You experience this as a normal app; Matrix handles the database behind the scenes.

Benefits:

• app data survives reloads and upgrades;
• lists and dashboards can filter, sort, and count records;
• multiple apps can use reliable structured data;
• recovery can restore data from Postgres snapshots;
• the platform does not need to own your app data.

Backups And Recovery

Customer VPSes run scheduled database backups. The backup flow uploads a timestamped Postgres snapshot before updating the system/db/latest pointer used for recovery.

If a VPS has to be replaced, Matrix can provision a new one, restore the latest database snapshot, reload the host bundle, and bring the workspace back online.

Recovered:

• structured app and workspace data from the latest successful Postgres snapshot;
• machine metadata needed for routing and recovery;
• files and app assets that are part of the Matrix home and backup materialization flow.

Not recovered:

• unsaved in-memory process state;
• changes made after the last successful backup;
• data from external services that lives outside Matrix unless it is synced or imported.

Privacy And Control

Matrix is designed so user data is not casually mixed into the platform:

• personal files live in the user's Matrix home;
• app/workspace records live in the user's Matrix database;
• platform-owned integrations keep provider credentials on the platform;
• customer VPSes call platform integration routes through a per-host token;
• apps use scoped APIs instead of raw platform secrets.

What Users Need To Do

Most users do not need to do anything technical. Use Matrix normally:

• create apps;
• connect services;
• organize files;
• ask Matrix to save important information;
• export or delete data when needed.

For power users and developers, Matrix can expose more detail through files, app manifests, and developer tooling, but that is optional.

Related Guides