> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/capacity-planning.md).

# Capacity planning

In SonarQube Server 2026.5, size CPU, memory, and storage for the Hunter Agent, the Remediation Agent, and Vortex analysis, and configure autoscaling for each.

Sizing an agentic deployment means sizing three things separately: the shared Agent Orchestrator, the agent runtimes, and the long-lived Vortex analysis service. None of them scale the same way, and none of them run in isolation from the others.

This page gives you defaults to start from, explains how to scale each component as your workload grows, and shows a worked example that ties the pieces together.

{% hint style="info" %}
Read [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md) first, and provision [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md) before you size your deployment. Use the values on this page when you write the Helm chart or Docker Compose configuration in the next step.
{% endhint %}

## What you're sizing <a href="#what-youre-sizing" id="what-youre-sizing"></a>

See [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#how-a-job-runs) for how these components fit together.

| Component                 | Lifecycle                                                    | Scales with                                     |
| ------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| Agent Orchestrator        | One long-lived instance, shared by both agents               | Number of active projects                       |
| Hunter Agent runtime      | Long-lived, KEDA-scaled; each replica runs one job at a time | Number of concurrent Hunter Agent jobs          |
| Remediation Agent runtime | Long-lived, KEDA-scaled; each replica runs one job at a time | Number of concurrent Remediation Agent jobs     |
| Vortex analysis           | Long-lived, shared by all Remediation Agent jobs             | Verification request volume                     |
| Egress proxy              | Fixed high-availability pair                                 | Not scaled; sized for throughput, not job count |

{% hint style="info" %}
The MCP server that exposes agent capabilities to IDEs and CI is not covered on this page. Its chart defaults set no resource requests or limits (`mcp.resources: {}`), so Kubernetes runs it with the BestEffort quality of service. Set your own requests and limits in `mcp.resources`.
{% endhint %}

## Per-container resource defaults <a href="#resource-defaults" id="resource-defaults"></a>

These are the current chart defaults. Set them in the Helm chart values for Kubernetes, see [Deploying with the Helm chart](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md), or in your Compose file for Docker Compose, see [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md).

| Component                              | CPU request | CPU limit | Memory request | Memory limit | Ephemeral storage request | Ephemeral storage limit |
| -------------------------------------- | ----------- | --------- | -------------- | ------------ | ------------------------- | ----------------------- |
| Agent Orchestrator                     | 250m        | 1 vCPU    | 512Mi          | 1Gi          | 512Mi                     | 2Gi                     |
| Hunter Agent runtime                   | 1 vCPU      | 2 vCPU    | 8Gi            | 8Gi          | 15Gi                      | 15Gi                    |
| Remediation Agent runtime              | 1 vCPU      | 4 vCPU    | 2Gi            | 8Gi          | 10Gi                      | 50Gi                    |
| Vortex analysis                        | 1 vCPU      | 2 vCPU    | 6Gi            | 8Gi          | 2Gi                       | 2Gi                     |
| Egress proxy (per replica, fixed at 2) | 50m         | 250m      | 64Mi           | 128Mi        | 64Mi                      | 128Mi                   |

The gVisor installer runs on each node, not per job, and uses up to 0.5 vCPU and 256Mi, with requests of 100m and 128Mi. It does not run on OpenShift, where the agent runtimes use Kata through `OpenShift.agentRuntimeClassName`, or on managed nodes with an immutable OS. The key-derivation job that provisions signing keys runs once per install or upgrade and its resource use is negligible.

{% hint style="info" %}
**Why request and limit differ.** The Hunter Agent runtime requests its full memory and ephemeral storage limit, and Vortex analysis requests its full ephemeral storage limit. Disk is not compressible, so each needs a fixed amount to hold a repository or a file's context and cannot run usefully below it. Every other request sits below its limit so the container can burst when a job needs it. CPU is burstable on every component, since average use is a fraction of a core.
{% endhint %}

{% hint style="warning" %}
Repositories larger than roughly 250MiB compressed can push the Hunter Agent runtime to 4 vCPU and 20Gi of ephemeral storage. This affects a small share of repositories, but size for it if you have large monorepos.
{% endhint %}

## Sizing by scale <a href="#sizing-by-scale" id="sizing-by-scale"></a>

### Hunter Agent runtime, by repository size <a href="#hunter-by-repo-size" id="hunter-by-repo-size"></a>

Measured against real production jobs, most repositories fit comfortably within the default limit:

| Repository size (compressed) | Share of jobs | CPU    | Memory | Ephemeral storage |
| ---------------------------- | ------------- | ------ | ------ | ----------------- |
| Small, under 50MiB           | About 95%     | 2 vCPU | 8Gi    | 15Gi              |
| Large, 50 to 250MiB          | About 4%      | 2 vCPU | 8Gi    | 15Gi              |
| Extra-large, over 250MiB     | About 1%      | 4 vCPU | 8Gi    | 20Gi              |

### Remediation Agent runtime, by project size <a href="#remediation-by-project-size" id="remediation-by-project-size"></a>

The request-to-limit range (1 vCPU/2Gi/10Gi up to 4 vCPU/8Gi/50Gi) covers projects up to roughly one million lines of code. Small and moderately sized projects run near the request; the runtime bursts toward the limit as project size grows, mainly because it clones the whole repository before it starts.

### Agent Orchestrator, by number of active projects <a href="#orchestrator-by-project-count" id="orchestrator-by-project-count"></a>

| Active projects | CPU    | Memory | Ephemeral storage |
| --------------- | ------ | ------ | ----------------- |
| Fewer than 500  | 250m   | 512Mi  | 512Mi             |
| More than 2,500 | 1 vCPU | 1Gi    | 2Gi               |

These are the current defaults. Revise them against your own usage once you have projects running, the same way you would for the storage figures in [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md).

## Autoscaling <a href="#autoscaling" id="autoscaling"></a>

The Helm chart supports autoscaling for every component except the egress proxy, which stays fixed. Autoscaling is off by default for every component: turn it on per component with `<component>.autoscaling.enabled: true`. Docker Compose has no autoscaling; see [#docker-compose](#docker-compose "mention").

| Component                 | Trigger                                                                    | Minimum replicas | Maximum replicas | Notes                                                                                                                                              |
| ------------------------- | -------------------------------------------------------------------------- | ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent Orchestrator        | Kubernetes Horizontal Pod Autoscaler (HPA) on CPU utilization (75% target) | 2                | 5                |                                                                                                                                                    |
| Hunter Agent runtime      | Kubernetes Event-driven Autoscaling (KEDA), on job queue depth             | 2                | 25               | Polls every 15 seconds; scales down after 600 seconds of no demand                                                                                 |
| Remediation Agent runtime | KEDA, on job queue depth                                                   | 2                | 25               | Uses a separate scaled object from the Hunter Agent runtime                                                                                        |
| Vortex analysis           | KEDA, on concurrent requests per replica (target 2)                        | 3                | 20               | Scales down after 900 seconds; needs Layer 7 load balancing to distribute traffic evenly, see [#load-test-findings](#load-test-findings "mention") |
| Egress proxy              | Not autoscaled                                                             | 2                | 2                | Fixed high-availability pair, with a pod disruption budget requiring at least 1 available                                                          |

Before you turn on autoscaling for the agent runtimes or Vortex analysis:

* Install KEDA separately. The chart README recommends a cluster-wide install rather than the `keda.enabled` subchart.
* Vortex analysis autoscaling needs KEDA 2.20 or later (`aggregateAcrossReplicas: true`).
* The KEDA-scaled agent runtimes never scale to zero: `minReplicas` must be 2 or more.

{% hint style="info" %}
Under load testing, a Hunter Agent runtime fleet scaling from 2 to 25 replicas completed a batch of 50 projects scheduled in a day in about 6 hours. A Remediation Agent runtime backlog of roughly 1,000 jobs completed with a 90% success rate and a 95th-percentile completion time of about 5 hours at 10 replicas, improving to about 55 minutes at 50 replicas. A batch of roughly 1,000 projects dispatched on the same schedule finished dispatching in under 13 minutes at 25 replicas. For context, a Hunter Agent job can run for up to about 12 hours and a Remediation Agent job for up to about 30 minutes. Treat these figures as a starting point: your own success rate and completion time depend on your job mix, your LLM provider's latency, and your cluster's available capacity.
{% endhint %}

## Storage <a href="#storage" id="storage"></a>

Agent job artifacts and Vortex analysis context are sized separately, and both are already covered elsewhere:

* For the durable and peak storage formulas for agent job artifacts, see [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#sizing).
* For Vortex analysis context, which is considerably larger and manages its own lifecycle, see [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md#storage-capacity).

{% hint style="warning" %}
The durable storage formula estimates job metadata, logs, and issue detail. It does not account for the compressed repository archive a Remediation Agent job creates, which can persist in object storage after the job completes until your own bucket lifecycle policy removes it. Apply a lifecycle policy on the job artifact location, as described in [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#retention), and expect real usage to run higher than the durable storage formula alone would suggest until you do.
{% endhint %}

### Choosing a storage backend by cloud provider <a href="#backend-by-provider" id="backend-by-provider"></a>

| Provider     | Object storage       | Single-node fileshare | Multi-node fileshare |
| ------------ | -------------------- | --------------------- | -------------------- |
| AWS          | Amazon S3            | Amazon EBS            | Amazon EFS           |
| Google Cloud | Google Cloud Storage | Persistent Disk       | Filestore            |
| Azure        | Azure Blob Storage   | Managed Disks         | Azure Files          |

Object storage is the simplest choice on every provider and is the default. Choose a fileshare option only if your infrastructure already standardizes on one, since it requires the `ReadWriteMany` access mode described in [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#shared-filesystem).

## Load test findings <a href="#load-test-findings" id="load-test-findings"></a>

{% hint style="info" %}
These findings come from load testing under specific traffic patterns, so treat them as a starting point and revisit them against your own traffic once you have it.
{% endhint %}

**Vortex analysis needs Layer 7 load balancing to scale.** A Kubernetes `ClusterIP` service balances at the TCP connection level, not per request. Under sustained load, this let traffic concentrate on a subset of Vortex analysis replicas regardless of how many replicas were running, so adding replicas did not raise the throughput ceiling. Set `istio.enabled=true` (requires Istio in sidecar mode) or put Vortex analysis behind another per-request load balancer.

**Verification-related API endpoints can bottleneck on the SonarQube Server application tier, not on Vortex analysis.** Under load, the `contexts` and `context-uploads` endpoints saturated the SonarQube Server application pods' CPU limits while Vortex analysis itself stayed nearly idle. If you see slow verification and Vortex analysis is not under load, check the application tier's replica count, CPU limit, and database connection pool instead of scaling Vortex analysis.

**Size the SonarQube Server application tier's memory and ephemeral storage for upload volume.** Under sustained upload load, application pods with a container memory limit well above the JVM heap size still ran out of ephemeral storage and were killed and restarted repeatedly. Raising the ephemeral storage limit and aligning the JVM heap size with the container's memory limit resolved it. Check both settings if you see application pods restarting during heavy context upload activity. The SonarQube Server 2026.5 Helm chart defaults already include this fix: memory is a 4096M request and a 10240M limit, sized to the new Web and Compute Engine heap defaults, and the ephemeral storage limit is 512000M. This advice matters mainly if you override those defaults.

## Worked example <a href="#worked-example" id="worked-example"></a>

A mid-size install with roughly 500 active projects, both agents enabled, around 500 Remediation Agent jobs a day, and 10 replicas each for the Hunter Agent and Remediation Agent runtimes and 3 replicas for Vortex analysis:

| Component                 | Replicas | CPU (limit)     | Memory (limit) | Ephemeral storage (limit) |
| ------------------------- | -------- | --------------- | -------------- | ------------------------- |
| Agent Orchestrator        | 1        | 1 vCPU          | 1Gi            | 2Gi                       |
| Hunter Agent runtime      | 10       | 20 vCPU         | 80Gi           | 150Gi                     |
| Remediation Agent runtime | 10       | 40 vCPU         | 80Gi           | 500Gi                     |
| Vortex analysis           | 3        | 6 vCPU          | 24Gi           | 6Gi                       |
| Egress proxy              | 2        | 0.5 vCPU        | 256Mi          | 256Mi                     |
| **Total**                 |          | **\~67.5 vCPU** | **\~185Gi**    | **\~658Gi**               |

Add up to 0.5 vCPU and 256Mi per node for the gVisor installer, and add the durable shared storage separately: at 500 jobs a day with 14-day retention, that's about 500 × 14 × 1 MB, or roughly 7GB, plus tens of megabytes of peak in-flight storage for repository archives.

Totals sum each component's limit rather than its request, so this is the capacity to provision, not the average you'll actually use.

## Docker Compose <a href="#docker-compose" id="docker-compose"></a>

Docker Compose has no autoscaling, so total capacity is whatever you define up front:

* Size each service like its Kubernetes counterpart, using the tables in [#resource-defaults](#resource-defaults "mention") and [#sizing-by-scale](#sizing-by-scale "mention").
* The Agent Orchestrator and Vortex analysis stay long-lived, so size them once for steady-state load, the same as their Kubernetes Deployment counterparts.
* The sandbox is still mandatory. Docker cannot cap a container's disk usage on its own, so `runsc` provides that through the bounded overlay described in [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md#sandboxing).
* Total host capacity is the sum of the long-lived services, plus the number of Hunter Agent runtime services times the Hunter Agent runtime's limit, plus the number of Remediation Agent runtime services times the Remediation Agent runtime's limit. Each runtime service runs one job at a time, so the number of services sets how many jobs can run concurrently. Reserve all of it up front, since nothing scales it for you.

## Next step <a href="#next-step" id="next-step"></a>

With your deployment sized, deploy the Agent Orchestrator and the agent runtimes. See [Deploying with the Helm chart](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md) for Kubernetes, or [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md) for Docker Compose.

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

* [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md)
* [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md)
* [Deploying with the Helm chart](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md)
* [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md)
* [Configuration reference](/sonarqube-server/server-installation/ai-agents/configuration-reference.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.sonarsource.com/sonarqube-server/server-installation/ai-agents/capacity-planning.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.