Releases
Host bundles, channels, and customer VPS updates.
Production Matrix OS runtime is VPS-native per user. Releases publish immutable host bundles, register release metadata, promote channels, and update customer VPSes in place.
Release shape
- R2 stores immutable host bundle bytes at
system-bundles/<version>/matrix-host-bundle.tar.gz. - Platform Postgres stores release metadata and channel pointers.
- Each VPS records its installed version at
/opt/matrix/release.json. - The gateway captures its running version once at process startup from
/opt/matrix/app/BUNDLE_VERSION. - Updates replace
/opt/matrix/appand runtime bundle contents, not owner data under the Matrix home.
Installed versus running identity
Installed release metadata and running process identity answer different questions. The release
file records which artifact an update installed; it does not prove that systemd replaced the old
gateway process. /api/system/info reports both values, while /health reports the startup-captured
running version used by update verification.
The updater must stop all runtime services before replacing /opt/matrix/app. After the new services
start, it waits for the gateway to report the exact candidate version. Only then may it commit installed
release metadata. A missing or mismatched running version fails verification and restores the previous
app tree instead of leaving a release that looks installed while old code is still serving requests.
Channels
| Channel | Typical source |
|---|---|
dev | Main branch host-bundle workflow. |
canary | Version tags or manual dispatch for early verification. |
beta | Wider pre-stable validation. |
stable | Production promotion after live verification. |
Golden snapshot trigger
Golden VPS snapshots are a forward-only acceleration for new machine creation.
Promoting an eligible immutable host bundle to stable records the stable
pointer, eligibility, and exact snapshot build request in one platform
transaction. Stable promotions default to eligible and can explicitly opt out;
other channels do not automatically enqueue snapshot builds.
The worker does not scan historical releases for missing snapshots. A newer stable promotion supersedes unfinished older build work, while historical release and audit records remain intact. Provisioning selects a ready snapshot only when its immutable bundle SHA-256 exactly matches the requested release; otherwise it uses the clean Ubuntu path.
Snapshot building and snapshot selection remain separately controlled. A stable promotion can record durable work while build workers or customer selection are disabled for rollout safety.
Local emergency build
set -a
source .env
set +a
HOST_BUNDLE_VERSION=<version> HOST_BUNDLE_CHANNEL=<channel> MATRIX_BUILD_SHA=$(git rev-parse HEAD) MATRIX_BUILD_REF=main ./scripts/build-host-bundle.shPublish
./scripts/publish-release.sh <version> --channel <channel>Verify
For every target VPS, verify:
/opt/matrix/app/BUNDLE_VERSION/opt/matrix/release.json/healthreports the same running version as the installed candidatematrix-gatewaymatrix-shellmatrix-sync-agent- local health
Protect owner data
Never overwrite user-owned Matrix home data during an update: desktop state, themes, wallpapers, icons, identity, profile, sessions, logs, memory, conversations, app data, and project files must remain owner-controlled.
How is this guide?