> 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/system-requirements.md).

# System Requirements

Host requirements for private cloud and on-premises deployments: CPU, memory, disk, operating systems, external and internal ports, recommended sizing by user count, and GPU node driver and compute ca

This page lists the host specifications and network requirements for installing MaiAgent with a deployment package (private cloud or on-premises). It is intended for customer IT teams and SI partners planning hardware and networking. For differences between deployment types, see [Deployment Types and Feature Comparison](/tech/en/platform-development/onprem-deployment-types.md).

{% hint style="info" %}
A basic deployment requires at least **32 GB of RAM and 60 GB of available disk space** reserved for MaiAgent. These are the minimum reserved resources for a basic deployment. Production sizing still requires a usage assessment. Additional space for models, documents, images, backups, and upgrades is separate.
{% endhint %}

## Host Thresholds <a href="#host-thresholds" id="host-thresholds"></a>

Single-host Docker, distributed Docker, and application/data hosts in existing deployments must meet the following minimum reserved resources. Expand resources first if they fall short. Hosts running only a reverse proxy and Kubernetes control-plane hosts require separate assessment. Plan Kubernetes worker nodes according to the [sizing profile](#kubernetes-sizing), services, and replica counts.

| Item                                                                                                                   | Minimum reserved resources | Recommended (lower specifications are suitable only for testing and PoCs) |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------- |
| CPU                                                                                                                    | —                          | 8 vCPU                                                                    |
| Memory (RAM)                                                                                                           | 32 GB                      | 48 GB                                                                     |
| Available disk space (the disk containing the deployment directory; also check the Docker data disk if it is separate) | 60 GB (fresh installation) | 200 GB                                                                    |

* Memory is assessed using the system-reported value, which is slightly lower than the nominal capacity (a 64 GB host reports about 61 GB). The check already accounts for this difference.
* The 60 GB requirement refers to available disk space before installation, not total disk capacity. Downloading and loading images consume space at the same time. Reserve additional space for the deployment contents and run the deployment package's `--check` before installation.
* Upgrades require additional space for the new deployment package and images. See [Versions and Upgrades: Disk Space to Prepare Before Upgrading](/tech/en/platform-development/onprem-versioning-and-upgrades.md#upgrade-disk-space).

## Recommended Sizing by User Count <a href="#sizing-by-users" id="sizing-by-users"></a>

Recommended specifications for single-host Docker with all services on one host, excluding GPU resources needed to run models locally:

| Users served  | Recommended specifications                                                                |
| ------------- | ----------------------------------------------------------------------------------------- |
| Up to 200     | 12 vCPU / 64 GB                                                                           |
| Up to 400     | 16 vCPU / 64 GB                                                                           |
| More than 400 | Distributed Docker or Kubernetes is recommended; contact MaiAgent for a sizing assessment |

These figures come from MaiAgent load testing and assume that about 20% of users are online concurrently. If the actual workload differs substantially (knowledge base size, file parsing volume, or concurrent conversations), contact MaiAgent for a reassessment.

Distributed Docker can separate application services, data services, and background jobs onto different hosts. Each host running services must reserve at least 32 GB RAM and 60 GB of available disk space. For the topology, see [Deployment Types and Feature Comparison: Distributed Docker](/tech/en/platform-development/onprem-deployment-types.md#docker-distributed).

## Kubernetes Sizing Profiles <a href="#kubernetes-sizing" id="kubernetes-sizing"></a>

Kubernetes deployments allocate storage capacity for each service according to the sizing profile:

| Profile | Use case        | PostgreSQL | Redis | Object storage | Elasticsearch (capacity / heap) | Image registry |
| ------- | --------------- | ---------- | ----- | -------------- | ------------------------------- | -------------- |
| test    | Single-node PoC | 5Gi        | 2Gi   | 5Gi            | 5Gi / 2g                        | 30Gi           |
| small   | Up to 10 users  | 10Gi       | 2Gi   | 20Gi           | 10Gi / 4g                       | 50Gi           |
| mid     | Up to 100 users | 20Gi       | 5Gi   | 50Gi           | 30Gi / 8g                       | 50Gi           |
| large   | Production      | 100Gi      | 10Gi  | 200Gi          | 100Gi / 16g                     | 100Gi          |

* The image registry is installed only in multi-node deployments. Single-node deployments import images directly into the node and do not use the space in this column.
* Elasticsearch reserves memory equal to the heap size, with a limit of twice the heap size (mid: 8Gi / 16Gi). The node must have enough available memory.
* On a single node, all storage capacities use the same host storage path. The storage component (Longhorn) reserves 20% of the disk as unused space. If capacity is insufficient, services remain Pending and installation fails partway through. Choose a smaller profile or use a larger disk.

## Operating Systems and Accounts <a href="#operating-systems" id="operating-systems"></a>

| Item             | Requirement                                                                             |
| ---------------- | --------------------------------------------------------------------------------------- |
| Operating system | Ubuntu 22.04 / 24.04 / 26.04, RHEL 8 / 9, Rocky Linux 8 / 9                             |
| CPU architecture | amd64 or arm64                                                                          |
| Account          | A regular account with sudo privileges; the installer does not accept execution as root |
| Docker           | No preinstallation required; installed during deployment                                |

* **RHEL / Rocky Linux**: disable SELinux and reboot first. Offline installation on RHEL / Rocky 8 requires version 8.10 or later.
* **Kubernetes 1.36 on RHEL / Rocky 8**: requires version 8.6 or later and a switch to cgroup v2.
* For offline installation, the deployment package must include offline packages for the target host's operating system. The host inventory lists the required versions. If any are missing, ask MaiAgent for the appropriate deployment package.

## Ports <a href="#ports" id="ports"></a>

**Ports that must not be occupied by other services on the host**: 80, 443, 5432, 6379, 9000, and 9200; also 8000, 3333, and 3334 when connecting by IP address and port.

**Ports to expose to users** (firewall or security group):

| User connection method | Ports to expose                                                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| IP address and port    | 8000 (API), 3333 (admin console), 3334 (chat page), 9000 (object storage; browsers connect directly to this port to upload and download files) |
| One domain per service | 80, 443                                                                                                                                        |

* Kubernetes supports only one domain per service.
* Distributed Docker: the deployment host must be able to log in to the other hosts using SSH keys. Hosts also need connectivity to each other for databases, caching, search, object storage, and message queues. The exact list depends on the topology; contact MaiAgent for details.

**Destinations the host must reach during online installation** (not required for offline installation): MaiAgent's image and deployment package download sites, Hugging Face (to download weights for locally hosted models), Docker Hub (images for local model services), Docker's official package repositories, PyPI, and the operating system's package repositories. If access is allowlist-only, requires a proxy, or reaches only some of these destinations, use offline installation. See [Operations Essentials: Offline Installation](/tech/en/platform-development/onprem-operations.md#air-gap-install).

### Outbound Connections During Operation <a href="#outbound-connections" id="outbound-connections"></a>

After installation, the platform requires outbound host connectivity only when the corresponding features are used. All connections are initiated by the MaiAgent host, so the firewall only needs to allow traffic from the host to the destination. The platform can operate without any of these connections (using only models on the host and no external systems).

| Feature                                                                                                          | Destination                                                                                                                              | Common ports                                            |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Model service on another host or in the cloud                                                                    | Model service URL or cloud provider API endpoint                                                                                         | 443, or a custom model service port                     |
| Database feature (Text to SQL) connecting to an existing customer database                                       | Customer's PostgreSQL, MySQL, SQL Server, Oracle, or SynxDB                                                                              | 5432, 3306, 1433, 1521 (depending on database settings) |
| Knowledge base using [bring your own vector database](/tech/en/platform-development/bring-your-own-vector-db.md) | Customer's Elasticsearch, OpenSearch, Oracle, or SynxDB                                                                                  | 9200, 1521, 5432                                        |
| Messaging platforms (LINE, Teams, Email, etc.)                                                                   | Each platform's API; Email also requires SMTP / IMAP servers                                                                             | 443; SMTP 25 / 465 / 587                                |
| Invitation and notification emails                                                                               | Customer's SMTP server                                                                                                                   | 25 / 465 / 587                                          |
| Crawling, web search, maps, image and video generation                                                           | Corresponding cloud services (see [Feature Availability](/tech/en/platform-development/onprem-deployment-types.md#feature-availability)) | 443                                                     |
| Single sign-on (SSO) and LDAP identity synchronization                                                           | Customer's IdP or directory server                                                                                                       | Depends on the IdP; LDAP 389 / 636                      |
| Self-hosted MCP Server and API tools                                                                             | Customer-specified URLs                                                                                                                  | Depends on the service                                  |

* **Outbound connections only, no inbound connections**: the customer's internal systems do not need to initiate connections to the MaiAgent host. Exceptions are messaging platform webhooks (platforms such as LINE and Messenger must be able to call the MaiAgent API over the internet) and API integrations developed by the customer.
* **Internal networks**: the customer's network team plans routing between the host and internal databases or model hosts. The deployment package does not include networking components such as VPNs, dedicated connections, or VPC peering. When the host runs in the customer's cloud environment, use the customer's existing cloud-to-data-center connection (VPN or dedicated connection) to reach databases in the data center.
* **SaaS connections to customer internal databases** originate from MaiAgent cloud services. Allow the source IP addresses through the customer's firewall; contact your MaiAgent representative to obtain them. For other connection methods, such as VPN or VPC peering, contact MaiAgent for an assessment first. For database-side checks, see the user manual's [Create and Configure a Database: Network Prerequisites](https://docs.maiagent.ai/build/database/create-database#network-prerequisites).

## GPU Nodes <a href="#gpu-nodes" id="gpu-nodes"></a>

The platform itself does not require a GPU. A GPU is needed only for self-hosted model services or offline speech recognition on the host:

| Item                     | Requirement                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating system         | Same as the platform host (Ubuntu 22.04 / 24.04 / 26.04, RHEL 8 / 9, Rocky Linux 8 / 9; amd64 or arm64); see [Operating Systems and Accounts](#operating-systems)    |
| GPU                      | NVIDIA GPU with compute capability 7.0 or later, such as V100, A100, or H100                                                                                         |
| NVIDIA driver            | 525.60 or later                                                                                                                                                      |
| NVIDIA Container Toolkit | Installed automatically during deployment (online and offline installation support Ubuntu and RHEL / Rocky; offline packages are included in the deployment package) |
| GPU container runtime    | Deployment configures Docker (or the container runtime on Kubernetes nodes) to use the NVIDIA runtime; existing drivers, Toolkit, and runtime on the host are reused |

* **Driver installation responsibility**: for online installation on Ubuntu, deployment automatically installs the most suitable NVIDIA driver and reboots. For RHEL / Rocky Linux or offline installation, install the driver yourself before deployment and confirm that `nvidia-smi` runs successfully.
* **NVSwitch platforms** (SXM GPUs in HGX / DGX) require NVIDIA Fabric Manager to be enabled in the deployment configuration.
* Model configurations using FP8 (FP8 KV cache) require Ada Lovelace, Hopper, or Blackwell GPUs. Ampere GPUs (such as A100) are unsupported. For GPU recommendations by model, see [GPU Hardware Planning](/tech/en/platform-development/gpu.md).
* **NVIDIA GB10** (Dell Pro Max GB10, DGX Spark; GPU and system share 128 GB of memory) requires a different GPU attachment method. The combined memory utilization ratio of all model services on the same host should not exceed 0.92. Inform MaiAgent when planning deployment.
* Deployment templates support only NVIDIA GPUs. Contact MaiAgent to assess other accelerators.
* Offline speech recognition requires a GPU. Offline document parsing (Docling) itself does not require a GPU; describing images within documents requires a connection to an OpenAI-compatible LLM (such as a model service on the host).

## Related Pages <a href="#related-pages" id="related-pages"></a>

* [Deployment Types and Feature Comparison](/tech/en/platform-development/onprem-deployment-types.md)
* [Connecting On-premises Model Services](/tech/en/platform-development/onprem-model-services.md)
* [GPU Hardware Planning](/tech/en/platform-development/gpu.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/system-requirements.md?ask=<question>&goal=<user_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.