> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/platform-development/onprem-versioning-and-upgrades.md). # Versions and Upgrades How private cloud and on-premises quarterly releases (2026.Qn) are numbered, an overview of updates within a quarter and upgrades across quarters, estimated downtime, rollback limits, and why on-premi Private cloud and on-premises deployments use quarterly releases rather than following continuous SaaS updates. This page is for customer IT teams and SI partners responsible for maintenance scheduling and change management. It explains how to read version numbers, what to prepare for an upgrade, expected downtime, and how far you can roll back if something goes wrong. {% hint style="info" %} This page provides an overview for planning. The installation manual included with the deployment bundle contains the full upgrade procedure. The release notes MaiAgent provides with each new version describe feature changes and settings that need adjustment before or after an upgrade. Contact your MaiAgent representative to obtain these documents. {% endhint %} ## What Are Quarterly Releases? * **Release lines organized by quarter**: On-premises releases follow quarterly lines, such as `2026.Q2` and `2026.Q3`. Each quarterly line is maintained independently, with updates released throughout the quarter. * **Version number**: The quarter plus the release date, such as `2026.Q3-10.02`. * **A matched set of delivered versions**: Each release includes three version numbers for the backend, admin console, and chat page. Use the matched set provided by MaiAgent (for example, backend and admin console `2026.Q3-10.02` with chat page `2026.Q3-09.28`). * **Deployment bundle**: The installer has its own version. Replace it with the new deployment bundle during an upgrade. **Currently maintained quarterly lines**: `2026.Q3` (latest) and `2026.Q2` both continue to receive updates. `2026.Q1` no longer receives updates; upgrade to a maintained quarterly line. All new deployments use the latest quarterly line. Contact your MaiAgent representative to confirm whether a line is still maintained or to obtain the latest version numbers. **How to check the installed versions**: The backend, admin console, and chat page version fields in the deployment configuration show the versions installed on this host. You can also inspect the image tags used by each service container on the host (Docker: `docker compose ps`; Kubernetes: `kubectl get deploy -n maiagent -o wide`). ## On-Premises Feature Timeline New features launch on SaaS first and are included in on-premises deployments in later quarterly releases. As a result, fewer features are available on-premises than on SaaS at any given time. For example: * Office online editing (file library) is currently available only on SaaS and has not yet been included in a quarterly release. * AI Gateway and offline speech recognition using LocalAI deployed on the host are available starting with `2026.Q3`; they are not available in `2026.Q2`. Refer to the release notes for the features available in each quarterly release. For differences between private cloud and on-premises deployments, see [Deployment Types and Feature Comparison](/tech/en/platform-development/onprem-deployment-types.md#feature-availability). ## Updates Within a Quarter and Upgrades Across Quarters | | Update within a quarter | Upgrade across quarters | | ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Example | `2026.Q3-09.24` → `2026.Q3-09.30` | `2026.Q2` → `2026.Q3` | | Procedure | Same | Same | | Measured downtime | About 10 minutes | About 20 minutes (database schema update takes about 11 minutes) | | Additional considerations | — | Database schema updates take longer; system settings introduced in the new version use its defaults; review the adjustments listed in the release notes first | * The test environment contained very little data. More data means longer database schema updates. Allow extra downtime and notify users in advance. * **Feature flags are preserved**: Previously configured feature flags (including those changed by customers in the admin console) remain unchanged during upgrades. An upgrade only sets flags introduced in the new version and answers recorded in the Deployment Configuration Checklist that have never been applied. * **Official built-in Agents**: When upgrading to `2026.Q3-10.02` or later, the upgrade enables the official marketplace if it has never been configured on this host. To keep it disabled, answer “No” in the checklist before upgrading. * **Object storage keeps its existing engine**: Environments using MinIO continue to use MinIO after an upgrade. * **Only MaiAgent's own services are updated** (backend, background workers, admin console, chat page, and enabled optional components such as local model services). Configuration changes for components such as the reverse proxy, search engine, and database are not applied during an upgrade. The release notes will specify any required changes. ## Upgrade Procedure Overview {% stepper %} {% step %} ### Obtain the Current Deployment Configuration An upgrade reuses the deployment configuration from installation and changes only the version numbers, without reconfiguring it. This configuration contains model service keys. Store and transfer it according to your company's policies. {% endstep %} {% step %} ### Prepare the New Release Materials Before Starting For offline environments, download the new deployment bundle and images on a workstation with internet access, and verify each file's checksum. For connected environments, download them directly on the host. For private cloud, confirm that the deployment type in the deployment configuration is still set to private cloud. {% endstep %} {% step %} ### Replace the Deployment Bundle and Run Checks Place the new deployment bundle on the host and **keep the old deployment bundle directory** for rollback. Run the pre-installation checks to confirm that the version numbers and materials are correct. {% endstep %} {% step %} ### Run the Upgrade The upgrade program runs in this order: check the deployment bundle version and deployment type (private cloud or on-premises; stop without making any changes if they do not match) → automatic backup → replace the backend with the new version and update the database schema → background workers → admin console and chat page → confirm that all services are running the new versions. The pre-upgrade backup is marked for retention and will not be deleted based on age. {% endstep %} {% step %} ### Verify After the Upgrade Check each service's version number, run a functional acceptance test, verify how feature flags were applied, and log in to the admin console to confirm that existing knowledge bases and files are present. Once the new version is stable, remove the retention marker from the pre-upgrade backup. {% endstep %} {% endstepper %} ## Disk Space to Prepare Before an Upgrade | Location | Required space | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Installation account's home directory | About 7 GB for the new deployment bundle archive and about 7.7 GB after extraction; keep the old deployment bundle directory | | Deployment directory | About 8 GB for the new image files | | Docker data directory | About 8 GB for the new images after loading; old images are retained for rollback | | Backup directory | One full backup | ## Rollback Limits * **A full rollback requires the pre-upgrade backup**. If a service fails to switch versions during an upgrade, only that service automatically reverts to its old image. Services already updated before it and the updated database schema do not revert. The system will contain a mix of old and new versions, and you must restore the pre-upgrade backup. * **Data added after the upgrade will be lost**: Restoration returns the database, uploaded files, service configuration, and website certificates to their pre-upgrade state. * **Do not reverse the rollback order**: Restore the backup first, then switch back to the old deployment bundle directory. Running the old application with the new database schema prevents login; newer deployment bundles block this situation before making changes. * **Kubernetes**: Restoration restores only data and does not switch services back to old images. Contact MaiAgent for help reverting to an older version. * **Kubernetes cluster version**: An upgrade changes only the MaiAgent version, not the cluster version. Upgrading an existing cluster from 1.31 to 1.36 is currently unsupported. Measured results (single-host Docker): Rolling back after an update within a quarter took about 157 seconds to restore. Login was available within 10 seconds of completion, and the versions, database schema, and existing data all returned to their pre-upgrade state. {% hint style="warning" %} Before upgrading or rolling back distributed Docker or Kubernetes environments, confirm the upgrade plan and schedule with your MaiAgent representative. {% endhint %} ## Upgrading from 2026.Q2 to 2026.Q3 * Q3 feature flags are set for the first time during this upgrade. If the deployment configuration contains checklist answers, those answers are used; otherwise, defaults are used (listed in the release notes). To apply the checklist settings, replace the configuration with the upgrade configuration exported from the checklist before upgrading. * Q2's “Limit the number of assistants that can be created” setting becomes a numeric limit: selected plans allow at most 1 assistant, while unselected plans have no limit, matching the actual behavior in Q2. ## Related Pages * [Deployment Types and Feature Comparison](/tech/en/platform-development/onprem-deployment-types.md) * [Operations Essentials: Backup and Restore](/tech/en/platform-development/onprem-operations.md#backup-and-restore) * [System Requirements](/tech/en/platform-development/system-requirements.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/en/platform-development/onprem-versioning-and-upgrades.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.