File System

Files and Owner-Controlled Data

Identity, configuration, app code, agent definitions, and personal files live in your computer’s home directory. Structured app data and durable import state live in your own PostgreSQL database. You can inspect, export, and delete your data; backing up the home directory alone does not back up the database.

Device connections and selected-device upload flows are deferred to a later release.

Home Directory Structure

File-based state resides under ~/matrixos/ (configurable via MATRIX_HOME):

~/matrixos/
  +-- apps/              # Generated application projects
  |     +-- expense-tracker/
  |     +-- notes/
  |
  +-- .agents/
  |     +-- skills/      # Agent Skills directories (matrix-app-builder/SKILL.md, ...)
  |
  +-- agents/
  |     +-- custom/      # Agent prompt files (builder.md, researcher.md, ...)
  |     +-- knowledge/   # Knowledge files loaded into agent context
  |
  +-- system/
  |     +-- soul.md      # AI personality and values
  |     +-- identity.md  # AI public identity (name, avatar)
  |     +-- user.md      # Human user profile
  |     +-- config.json  # Channel tokens, heartbeat, approval policies
  |     +-- cron.json    # Scheduled tasks (interval, once, cron expressions)
  |     +-- theme.json   # Active theme (colors, background, dock config)
  |     +-- handle.json  # Federated handle registry
  |     +-- conversations/ # Multi-session conversation history (JSON files)
  |
  +-- data/              # Owner-selected files and legacy app exports
  |     +-- imports/bank.csv
  |     +-- imports/game.pgn
  |
  +-- modules/           # Deployed module services (React apps on ports 3100-3999)
  +-- logs/              # Activity and interaction logs (JSONL daily rotation)
  +-- .backup/           # Git-managed snapshots

First-Boot Template

On first boot, the gateway copies the home/ directory from the repository to ~/matrixos/ and initializes a git repository. This template includes default agents, starter skills, SOUL identity, and configuration.

Config File

~/matrixos/system/config.json is the central configuration:

{
  "channels": {
    "telegram": {
      "token": "bot-token-here",
      "allowFrom": [123456789]
    },
    "discord": {
      "token": "discord-bot-token"
    }
  },
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 30,
    "activeHours": { "start": 8, "end": 22 }
  }
}

New configuration sections are added additively -- existing sections are never modified by the system.

Theme System

The active theme is defined in ~/matrixos/system/theme.json. The shell's useTheme hook reads this file via the file watcher and applies CSS custom properties. Theme changes propagate instantly.

Matrix OS ships with 6 theme presets and supports custom backgrounds (patterns, solid colors, gradients, wallpapers), dock configuration (position, size, auto-hide), and full color customization.

Git Snapshots

Every file change triggers a git commit via the gitSnapshotHook. This provides:

• Version history -- roll back any file to any previous state
• Self-healing -- the Healer agent restores broken files from git history
• Sync -- the sync_files IPC tool can commit, push, and pull for cross-device sync
• Audit trail -- every change is tracked with timestamps

File Serving

The gateway exposes home-directory files and structured app data through separate endpoints:

Markdown previews render referenced SVG image assets inline. Local SVG paths are resolved through the same path-sandboxed /files/* serving route, while unsafe or broken SVG references degrade to a readable placeholder instead of interrupting the document.

File Watcher

A chokidar-based file watcher in packages/gateway/src/watcher.ts monitors ~/matrixos/ for changes. When files change, it broadcasts file:change events over WebSocket. The shell's useFileWatcher hook consumes these events to render updates in real time -- new apps appear as windows, theme changes apply instantly, and the dock updates automatically.

PostgreSQL Database

PostgreSQL managed through Kysely handles structured durable kernel and app data, including owner-scoped connected-data jobs and retained pages:

PostgreSQL provides concurrent access, transactions, and recovery for structured kernel and app state.