Releases

Understand Matrix OS host bundles, release channels, and customer VPS updates, with guidance on publishing, deployment verification, and data preservation.

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

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/app and 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.

Bot database schema compatibility

Bot startup applies supported database migrations automatically, under the schema transaction lock. It validates recorded migration versions and names before applying pending migrations. Owners do not need a separate manual SQL update for each user.

Migration 6, bot_chatgpt_plan_devices, retains the exact released table definition. On a fresh database it creates an empty table; if that migration is already recorded correctly, startup leaves the existing table and rows intact. The owner/computer device IDs and public keys are durable device trust pins, not disposable cache. Preserve them exactly, together with migration 5 provider authorizations, execution bindings, and conversation history. Recognizing this schema does not reset device trust or add permissions.

A recorded migration with a wrong name, or an unknown future version, blocks Bot startup before pending migrations are applied. Keep migration records and owner data intact when investigating a failure. General gateway health alone does not prove that Bot services started; verify Bot availability separately.

Schema recognition has a limited scope

Dormant schema recognition repairs the database startup barrier. It does not add provider execution or authorization services, or establish runtime backward compatibility. Canonical key and logout handling, native provider settings and workflows, selected execution routes, and ChatGPT Plan execution need their own reviewed compatibility checks before replacing a runtime. Preserved rows alone do not justify a deployment or a different model or funding route.

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.

Native mobile updates

Native Mobile uses its app version as the OTA runtime compatibility boundary. A dependency security update can change native fingerprint inputs even when application screens stay the same.

When native inputs change, increase the app version and create fresh preview and store builds before releasing updates for that runtime. Keep the native change guard enabled: an OTA update must never reach an older binary whose native inputs differ. Existing installations keep their compatible update until a new native build is installed.

A dependency pull request, passing bundle export, or runtime-version bump alone does not publish or qualify a native build. Verify the new build and its target release channel before promotion. See Native Mobile for the current product scope.

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

Terminal

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

Terminal

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

Verify

For every target VPS, verify:

/opt/matrix/app/BUNDLE_VERSION
/opt/matrix/release.json
/health reports the same running version as the installed candidate
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.

On this page