Multiplayer agent harness for work.
Runtime upgrade compatibility
Pin the runtime source or image digest and deployment CLI together. Run migrations before serving traffic, then qualify that exact candidate against an isolated copy of the existing database. Keep the previous images and deployment configuration available until the new revision has passed operational checks.
Configuration changes
qm sandbox publishand thesandbox.imageruntime pin are retired.qm sandbox buildremains available for validating local layer builds;sandbox.baseImageidentifies their build input. Supply sandbox tools through deployment layers and configure the selected backend through its supported settings.SANDBOX_SECONDARY_BACKENDis retired.SANDBOX_BACKENDselects the primary backend; additional configured backends become available through their credentials and backend settings. Remove the old secondary setting.- The
sandbox_routingtable,SANDBOX_RESOURCES_ENABLED, and the sandbox migration endpoints and agent action are retired. Sandbox resources are always on; scoped execution uses the selected sandbox resource. Disposable computers use that resource's provider, or the installation provider when no resource is selected. On upgrade, existing routes andSANDBOX_SCOPE_BACKENDSmappings are imported once as sandbox records so existing computers are preserved; afterwardsSANDBOX_SCOPE_BACKENDShas no runtime effect. To move a scope to another provider, create a sandbox there, copy durable work via git or Files, and set it as the default. Keep credentials and provider settings for all legacy mappings until the import completes; an unconfigured provider needed by the import stops startup before any adoption state is written. - Reach-denied Slack notifications are retired. Consult the audit log for denied requests.
Database upgrades and rollback
Migration identifiers and SQL checksums retain their original meaning. An existing checksum mismatch stops the upgrade; do not clear the migration ledger or edit its checksums to bypass this check. A previously completed legacy webhook sweep is adopted into the checksum ledger without disabling webhooks that an operator has subsequently re-enabled.
The cron journal imports existing cron_fire_log history into cron_fires and
continues importing writes from older workers during a rolling upgrade. History
retention also removes expired entries from the legacy table, preventing a later
restart from importing them again. The legacy table remains available for older
binaries.
Upgrading from a release that predates the items table copies session history
into items during startup migrations, then drops session_entries, session_tape
and the old search table. Stop every older core and worker first: they cannot run
against the new schema. src/sessions/legacy-history-migrations.ts keeps those released
migrations verbatim; delete it once every supported deployment has applied
sessions/store/0036-items-cutover. Upgrading from a release that still writes session_tape
first copies its step metadata into legacy_tape_steps, then drops the tape. Stop every
older core and worker before starting the new release: a tape write after the copy
starts makes the drop refuse, and that startup fails with the reset to run. The copy
runs on the direct migration connection without a statement timeout and resumes
after an interrupted startup. It walks every session at roughly 30 sessions per
second, so a few thousand sessions take a couple of minutes; above that, run
node src/migrate-main.ts with the release's configuration before starting the
servers so readiness checks do not time out. Instances that start meanwhile wait for the copy on
the migration lock.
Sessions created before QM recorded each session's origin get origin and origin_id
from their thread reference during startup migrations. The backfill commits 5,000
sessions at a time, resumes after an interrupted startup, and fills roughly 10,000
sessions per second; with more than a few hundred thousand such sessions, run
node src/migrate-main.ts with the release's configuration before starting the servers
so readiness checks do not time out.
Rolling back the runtime restores code and configuration, not database contents.
Older binaries do not display cron history written only to the new journal; those
records remain stored in cron_fires. Validate both old and new readers against the
candidate database before promotion, and retain a database recovery point for any
rollback that requires restoring data as well as code.