Releases

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.
Updates replace /opt/matrix/app and runtime bundle contents, not owner data under the Matrix home.

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.

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.sh

Publish

./scripts/publish-release.sh <version> --channel <channel>

Verify

For every target VPS, verify:

/opt/matrix/app/BUNDLE_VERSION
/opt/matrix/release.json
matrix-gateway
matrix-shell
matrix-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.