> 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-deployment-types.md). # Deployment Types and Feature Comparison How to choose among three private cloud and on-premises deployment types (single-host Docker, distributed Docker, and Kubernetes), plus a feature availability comparison across SaaS, private cloud, an MaiAgent private cloud and on-premises deployments use the same deployment package: run its installer on the customer's hosts to install platform services as Docker containers or Kubernetes workloads according to the deployment configuration. This page is for customer IT teams and SI partners evaluating or planning a deployment. It explains how to choose among the three deployment types, how private cloud differs from on-premises, and which features are unavailable in each environment. {% hint style="info" %} This page provides a summary for planning. For the complete installation procedure (host inventory, preparation, installation, and verification), see the installation manual included with the deployment package. Contact your MaiAgent representative to obtain it. For host specifications, see [System Requirements](/tech/en/platform-development/system-requirements.md). {% endhint %} ## Three Deployment Types | | Single-host Docker | Distributed Docker | Kubernetes | | ----------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | Architecture | All services run on one host | Services run across multiple hosts; one deployment host installs the others over SSH | The installer creates a cluster, or installs into the customer's existing cluster | | Suitable for | PoCs and production environments serving up to 400 users | Deployments that exceed a single host's capacity, or require separate hosts for the data layer and background jobs | Deployments requiring multi-node high availability, or customers with Kubernetes operations expertise | | User connection method | IP address and port, or one domain per service | Same as single-host Docker | Domains only (one per service); DNS is required | | Deployment package | Standard deployment package | Standard deployment package | A dedicated package generated by MaiAgent from the customer's deployment configuration | | Built-in backup scripts | Available | Available; backups are stored centrally on the deployment host | Available for installer-created clusters; use the cluster's own backup mechanism for existing customer clusters | | Code Interpreter (code execution sandbox) | Supported | Supported | Not supported | ### Single-host Docker * The primary scenario covered by the installation manual. In testing, installation on a 16 vCPU / 64 GB host took about 30 minutes, including about 16 minutes for database migrations. On an 8 vCPU / 32 GB host, it took 34–52 minutes, with most of the additional time spent on database migrations. * Services start automatically after a host reboot. The installer can be run again without losing existing data or changed passwords. * For recommended specifications by user count, see [System Requirements: Recommended Sizing by User Count](/tech/en/platform-development/system-requirements.md#sizing-by-users). ### Distributed Docker The installer runs only on the deployment host and installs the other hosts over SSH. Services can be split across three hosts. Each host running services must meet the [minimum reserved resources in System Requirements](/tech/en/platform-development/system-requirements.md#host-thresholds): | Host | Services | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | | Deployment host (application) | Reverse proxy, backend API, admin console, and chat page; the RabbitMQ message queue also runs here by default | | Data host | PostgreSQL, Redis, Elasticsearch, and object storage | | Background job host | Background jobs (normal and low priority), scheduler, and background job monitoring | * Use the same regular account with sudo privileges on every host. The deployment host must be able to connect to every other host using SSH keys. * For offline installation, place the installation materials on every host running Docker. * In testing, offline installation across three hosts took about 33–44 minutes. ### Kubernetes * **An environment-specific deployment package is required**: generate the deployment configuration and send it to MaiAgent, which generates a dedicated package for that environment. Use that package for installation. Later changes to sizing (capacity, memory, or replica counts) also require MaiAgent to regenerate the package. * **Cluster**: the installer can create a cluster (installing kubeadm, Cilium networking, and Longhorn storage), or use Helm to install into the customer's existing cluster. Three control-plane nodes are recommended for high availability. Multi-node deployments include an in-cluster image registry. * **Kubernetes version**: the default is 1.31; new clusters can use 1.36. Upgrading an existing cluster from 1.31 to 1.36 is currently unsupported. * **Sizing**: choose one of four profiles—test, small, mid, or large—based on the environment size. For capacities, see [System Requirements: Kubernetes Sizing Profiles](/tech/en/platform-development/system-requirements.md#kubernetes-sizing). * In testing, a single-node installation (16 vCPU / 64 GB, 200 GB disk, small profile), including the cluster itself, took about 35–37 minutes. * Rolling back to an earlier version requires assistance from MaiAgent. See [Versions and Upgrades](/tech/en/platform-development/onprem-versioning-and-upgrades.md#rollback). ## How to Choose 1. **Up to 400 users, with an acceptable full-system outage if the single host fails**: choose single-host Docker for the simplest operations. 2. **More than 400 users**: use distributed Docker or Kubernetes. Contact MaiAgent for a sizing assessment. 3. **Node-level high availability required**: choose multi-node Kubernetes. 4. **Agents need to execute code (Code Interpreter)**: currently supported only with Docker deployments. {% hint style="warning" %} The deployment type is determined during the initial installation. Switching from Docker to Kubernetes later requires data migration. Contact MaiAgent for an assessment first. {% endhint %} Deployment costs and timelines depend on user count, deployment type, GPUs and models, integrations, and customization scope. There is no fixed standard price or duration. Provide these details to your MaiAgent representative for an assessment and quote. ## Private Cloud vs. On-premises Private cloud and on-premises deployments use the same deployment package. The difference is the deployment category (private cloud or on-premises) in the deployment configuration, which determines whether features requiring cloud service connections are available: * **On-premises** (default): treated as an environment without access to cloud services. Voice Agents, the call center, cloud speech recognition, and cloud connectors are all disabled. * **Private cloud**: hosts can connect to cloud services, so these features can be enabled as needed. Hosting on a public cloud does not automatically mean the deployment category should be private cloud. Use the Deployment Configuration Confirmation Form agreed upon with MaiAgent before deployment. {% hint style="danger" %} Finalize the private cloud or on-premises category **before the initial installation**. Changing an on-premises deployment to private cloud afterward does not automatically enable these features. During an upgrade, if the deployment configuration does not match the host's current deployment category, the upgrade stops before making any changes. {% endhint %} ## Feature Availability Based on the 2026.Q3 quarterly release. Features in the SaaS column are enabled according to the plan and organization settings. “Configurable” in the private cloud and on-premises columns means the feature is enabled or disabled according to the Deployment Configuration Confirmation Form. | Feature | SaaS | Private cloud | On-premises | | ------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Voice Agents | ✓ | Configurable; requires deployment of real-time voice components | Unavailable | | Call center | ✓ | Configurable; enabled by default for new organizations | Unavailable | | Cloud speech recognition | ✓ | Configurable | Unavailable; use offline speech recognition instead | | Offline speech recognition (runs on the host; requires a GPU) | — | Optional | Optional | | Cloud connectors (Google Drive and other cloud services) | ✓ | Configurable | Unavailable | | AI Gateway | ✓ | Configurable; enabled by default for new organizations | Configurable; enabled by default for new organizations; self-hosted models only | | Bring your own vector database | ✓ | Enabled by default for new organizations | Enabled by default for new organizations | | Official built-in Agents (official marketplace) | ✓ | Enabled by default; can be disabled in the confirmation form | Enabled by default; can be disabled in the confirmation form | | Web search, maps, image and video generation | ✓ | Configurable; the host must be able to reach the corresponding cloud services and have API keys configured | Configurable; the host must be able to reach the corresponding cloud services and have API keys configured | | Crawler (importing web content into the knowledge base) | ✓ | Configurable; runs through a cloud crawling service that the host must be able to reach, with an API key configured | Same as private cloud; unavailable in fully offline environments | | Code Interpreter | ✓ | Configurable; Docker deployments only | Configurable; Docker deployments only | | Messenger, Instagram, and WhatsApp channels | ✓ | Disabled by default; see below | Disabled by default; unavailable in offline environments | | Office online editing (file library) | ✓ | Not yet included in quarterly releases | Not yet included in quarterly releases | * **Messenger, Instagram, and WhatsApp**: customers must provide their own Meta App, and Meta must be able to call the MaiAgent API over the internet. To enable these channels, send the Meta App settings to MaiAgent to regenerate the admin console image. Changing the deployment configuration alone does not take effect. * **AI Gateway** is available starting with 2026.Q3. See [AI Gateway: OpenAI-Compatible API Integration](/tech/en/ai-gateway/ai-gateway-openai-compatible.md). * For **bring your own vector database** specifications, see [Bring Your Own Vector Database](/tech/en/platform-development/bring-your-own-vector-db.md). * New features launch on SaaS first and are included in later quarterly on-premises releases. See [Versions and Upgrades: On-premises Feature Timeline](/tech/en/platform-development/onprem-versioning-and-upgrades.md#feature-timing). ## Related Pages * [System Requirements](/tech/en/platform-development/system-requirements.md) * [Versions and Upgrades](/tech/en/platform-development/onprem-versioning-and-upgrades.md) * [Connecting On-premises Model Services](/tech/en/platform-development/onprem-model-services.md) * [Operations Essentials: Offline Installation, Backups, TLS, Monitoring, and Acceptance](/tech/en/platform-development/onprem-operations.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-deployment-types.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.