> 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/reference-architectures/agentic-features-architecture.md). # Agentic features architecture The agentic features are optional. This page describes the components you add to a SonarQube Server 2026.5 installation to run them, and the resources that each component needs. ## Overview This architecture extends a reference architecture rather than replacing one. Start from the context that matches your code base, either [Up to 10 M LOC](/sonarqube-server/server-installation/reference-architectures/up-to-10m-loc.md) or [Up to 50 M LOC](/sonarqube-server/server-installation/reference-architectures/up-to-50m-loc.md), then add the components described here. The agentic features covered are the Hunter Agent, the Remediation Agent, and Sonar Vortex. They require the Enterprise or Data Center edition, and each agent requires a separate subscription. You can add them to an existing installation at any time, or leave them out. Three properties shape the architecture: * The components run as containers. SonarQube Server itself can still run from a ZIP file, from a Docker image, or on Kubernetes, but these components are available as containers only. * Jobs run in sandboxed runtime containers. The runtimes are long-lived and scale out with the job queue, so you size for concurrent jobs rather than for total jobs. * The components exchange data through shared storage that you provision and maintain, in the same way that you provision the database. Sizing is driven by how many agentic jobs you run and how large your repositories are, not by the number of lines of code in your instance. {% hint style="info" %} This page describes a single-node Enterprise edition deployment. {% endhint %} The following diagram shows which components you deploy and how they connect to an existing installation. The components you add are outlined in blue. Sandboxed containers, one per agentic job, have a dashed border. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F1F6FC', 'primaryBorderColor': '#126ED3', 'primaryTextColor': '#0A0A0A', 'lineColor': '#126ED3', 'secondaryColor': '#F4F6F8', 'tertiaryColor': '#F4F6F8', 'clusterBkg': '#F4F6F8', 'clusterBorder': '#D4D4D4', 'edgeLabelBackground': '#FFFFFF'}}}%% flowchart LR subgraph existing["Existing installation"] subgraph host["SonarQube Server host"] SQ["SonarQube Server
including the Agentic API"] end DB[("SonarQube Server
database")] end subgraph deploy["AI components you deploy"] AO["Agent Orchestrator"] HRT["Hunter Agent runtime"] RRT["Remediation Agent runtime"] PROXY["Egress proxy"] VX["Sonar Vortex"] end STORE["Shared storage
S3-compatible or shared filesystem"] LLM["Your LLM provider"] SCM["Your DevOps platform"] SQ -->|"Trigger job"| AO SQ <-->|"Analyzer context"| STORE AO -->|"Job state"| DB AO -->|"Dispatch job"| HRT AO -->|"Dispatch job"| RRT AO -->|"Clone code, open pull requests"| SCM HRT --> PROXY RRT --> PROXY PROXY -->|"Prompts"| LLM SQ <-->|"Analysis requests"| VX deploy <-->|"Stage code, read and write results"| STORE classDef neutral fill:#FFFFFF,stroke:#D4D4D4,color:#0A0A0A classDef external fill:#F4F6F8,stroke:#D4D4D4,color:#0A0A0A classDef subject fill:#FFFFFF,stroke:#126ED3,color:#0A0A0A classDef sandbox fill:#FFFFFF,stroke:#126ED3,color:#0A0A0A,stroke-dasharray: 5 5 class SQ,DB neutral class LLM,SCM external class AO,VX,PROXY,STORE subject class HRT,RRT sandbox style existing fill:#FFFFFF,stroke:#D4D4D4 style host fill:#F4F6F8,stroke:#D4D4D4 style deploy fill:#F1F6FC,stroke:#126ED3 ``` All runtime traffic leaves through the egress proxy on both deployment methods. On Kubernetes, network policies on the runtimes constrain them so they have no other route out, rather than replacing the proxy. The runtimes are also kept apart from each other: the same network policies do that on Kubernetes, and on Docker Compose you give each runtime its own network. ## Components | Component | Runs as | Purpose | | ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Agentic API | A process inside SonarQube Server | Exposes the agentic features to the UI and to automation. Needs no separate deployment | | Agent Orchestrator | One long-lived container | Coordinates every agentic job: stages the source code, dispatches the job to a runtime, tracks progress, and processes the results | | Agent runtime | Long-lived sandboxed containers that scale out with the job queue | Runs agentic jobs, reading the staged code and calling your LLM provider | | Egress proxy | A container, on both Docker Compose and Kubernetes | Restricts what a runtime container can reach to an allow list, and blocks everything else | | Sonar Vortex | Two or more long-lived containers | Analyzes single files on demand for SonarQube Server, including verifying the Remediation Agent's fixes. The Remediation Agent requires it | | Shared storage | Object storage or a shared filesystem that you provide | Carries source code snapshots and job results between the Orchestrator and the runtime containers | One Agent Orchestrator serves both agents, so you deploy it once regardless of how many agents you use. The Remediation Agent depends on Sonar Vortex, so enabling that agent means provisioning Sonar Vortex as well. For what each component does and how to deploy it, see [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md). ## Deployment methods | Method | Agent Orchestrator | Egress proxy | Job capacity | | -------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Kubernetes, using the Helm chart | Runs as a Deployment | A container to deploy and size, with network policies forcing runtime traffic through it | Fixed pool of 2 replicas per runtime family, or 2 to 25 with autoscaling enabled | | Docker Compose | Runs as a long-lived service | A container to deploy and size | Fixed pool | Kubernetes is the recommended method for production, because job capacity can grow and shrink with demand once you enable autoscaling. Docker Compose runs a fixed pool that you size for your peak, and is supported for environments that don't run Kubernetes. *The agentic features are available as containers only.* They cannot run from a ZIP installation, because the sandbox needs a container runtime. You can still run SonarQube Server itself from the ZIP file and deploy these components alongside it as containers. The hosts running these containers have their own requirements, including a minimum Linux kernel version and a sandbox runtime. Docker Desktop cannot run the agent runtimes. On OpenShift, they are sandboxed with Kata Containers rather than gVisor, which requires the OpenShift sandboxed containers operator. The gVisor default needs no hardware virtualization, so it runs on standard cloud instances, while another sandboxed runtime class may require more. See [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md). Traffic between SonarQube Server, the Agent Orchestrator, and the runtimes is unencrypted by default, on the basis that these components sit on a private network or cluster. Terminate transport encryption yourself if you need it. The host specifications on this page are the figures you plan a deployment around. For the full per-container requests and limits, the autoscaling ranges, and what load testing found, see [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.md). ## Agent Orchestrator The Orchestrator is a single long-lived container. It isn't on the job execution path, so its resource use scales with the number of projects that have an agent enabled rather than with repository size.
Host specification | | vCPU | Memory | | -------------------------------- | ---- | ------ | | Request, fewer than 500 projects | 250m | 512 MB | | Limit, more than 2,500 projects | 1 | 1 GB | The Orchestrator bursts between the two as demand grows rather than being resized, so an instance between 500 and 2,500 active projects sits inside that range. Run one Orchestrator per instance. It needs access to the SonarQube Server database and to shared storage. The Orchestrator reads SonarQube Server's schema and does not run migrations itself, so SonarQube Server has to be running, and migrated after an update, before the Orchestrator starts. On Kubernetes the Helm chart waits for that; on Docker Compose you sequence it yourself.
## Agent runtimes A runtime container handles one job at a time, so these figures are per concurrent job. Multiply them by the number of jobs you expect to run at the same time to get the capacity you need to reserve.
Hunter Agent host specification | Repository size | vCPU | Memory | Ephemeral storage | | ----------------------- | ---- | ------ | ----------------- | | Default | 2 | 8 GB | 15 GB | | Very large repositories | 4 | 8 GB | 20 GB | Memory stays at 8 GB in both cases. Start with the default, and raise the vCPU count and ephemeral storage only if you analyze repositories of several hundred megabytes.
Remediation Agent host specification The project sizes are the size of the project a job runs on, not the total size of your instance. | | vCPU | Memory | Ephemeral storage | | -------------------------------------------- | ---- | ------ | ----------------- | | Request, small and moderate projects | 1 | 2 GB | 10 GB | | Limit, large projects up to 1M lines of code | 4 | 8 GB | 50 GB | The container bursts between the request and the limit as a job needs it, rather than being resized for each project. Projects above 1M lines of code have not been profiled, so monitor jobs that run on repositories larger than that.
### Estimating concurrent jobs Job duration shapes how much runtime capacity you need at once: * A Hunter Agent job takes 2 to 3 hours on a medium-size repository, and times out after 12 hours and 20 minutes * A Remediation Agent job covers up to 50 issues in a run, and times out after 1 hour Each runtime family runs 2 replicas by default, and scales on the depth of the job queue to 25 once you enable autoscaling. A replica handles one job at a time, so your replica count is the ceiling on concurrent jobs per family, and 25 is the highest that ceiling goes. The Agent Orchestrator's own defaults handle a large job volume, so it isn't the limit you plan around. To estimate the Hunter Agent replicas you need, work from job duration. One replica completes roughly 8 jobs a day at a 3-hour average, which gives you: ``` Hunter Agent replicas ≈ (jobs per day ÷ 8) + margin for on-demand runs ``` **Example:** 200 projects analyzed weekly is about 29 jobs a day. That's 29 ÷ 8, plus a margin of 2, so reserve capacity for 6 concurrent replicas. ## Egress proxy The egress proxy forwards traffic rather than analyzing it, so it's the smallest of these components. Its allow list needs your LLM provider and SonarQube Server, plus your object storage endpoint if that is your backend. A shared filesystem is mounted rather than reached over the network.
Host specification | Category | Requirement | | -------- | -------------- | | vCPU | 0.25 | | Memory | 128 MB maximum | These are per container. On Kubernetes the proxy runs as a pair for availability, so reserve twice these figures.
## Sonar Vortex Sonar Vortex runs continuously rather than per job, and it serves analysis requests from SonarQube Server.
Host specification | Category | Requirement | | ----------------- | -------------------------------------- | | vCPU | 2 per replica | | Memory | 8 GB per replica | | Ephemeral storage | 2 GB per replica | | Replicas | 3, or 3 to 20 with autoscaling enabled | | Shared storage | About 300 MB per project | Run at least three replicas, which is the recommended minimum for a good experience, and autoscale to 20 if you enable autoscaling. Each replica serves two concurrent requests. Ephemeral storage holds working files that are deleted when an analysis finishes.
## Shared storage Two figures matter, and they behave differently. Durable capacity accumulates. Each completed job leaves roughly 1 MB of results, logs, and issue detail, and it stays until your retention policy removes it: ``` Durable capacity ≈ jobs per day × retention period in days × 1 MB ``` Peak capacity is what you need at any one moment, and it scales with the concurrency you configure rather than with job volume. While a job runs, a compressed archive of the repository sits in storage as well: ``` Peak capacity ≈ concurrent jobs × average compressed repository size ``` Add the two figures together, then add the Sonar Vortex footprint of about 300 MB per project if you deploy it. ### Worked examples These examples cover Remediation Agent jobs at the default 30-day retention. Replace them with your own project count, job frequency, and repository size. | Dimension | Small | Medium | Large | | ---------------------------------- | ---------------- | ----------------- | ----------------- | | Projects using an agent | 20 | 500 | 11,500 | | Jobs per day | 20 | 500 | 5,000 | | Average compressed repository size | 20 MB | 50 MB | 80 MB | | Durable capacity | \~600 MB | \~15 GB | \~150 GB | | Sonar Vortex storage, if deployed | \~6 GB | \~150 GB | \~3.4 TB | | Database growth | \~15 MB per year | \~365 MB per year | A few GB per year | If you deploy Sonar Vortex, its storage is the figure that determines the size of your backend. It scales with the number of projects rather than with job volume, so it grows independently of your retention policy, though it stays bounded, because context is purged for old analyses and for anything older than three months. {% hint style="warning" %} These figures are a starting point, not a commitment. They come from measurements on a validation instance at low job volume, so revise them against your own usage once you have it. {% endhint %} {% hint style="info" %} Retention is what keeps storage bounded. Job artifacts are deleted automatically after 30 days by default, and you set the period under **General Settings** > **Housekeeping** > **Agentic**. A lifecycle policy on the storage backend is worth adding as a backup, not as the mechanism. See [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#retention). {% endhint %} The database holds job metadata only, with no large objects, so it grows slowly and predictably. It's worth monitoring on very active instances, but it isn't the figure that determines your storage. ### Storage classes Agentic jobs read and write job artifacts in bursts, so general-purpose tiers suit them and archival tiers do not. The following classes were tested against a moderate-size project. | Platform | Object storage | Shared filesystem, single host | Shared filesystem, multiple hosts | | ------------ | ----------------------------------------- | ---------------------------------- | --------------------------------- | | AWS | S3 Standard | EBS gp3 | EFS Standard | | Google Cloud | Cloud Storage Standard | Balanced persistent disk | Filestore Zonal or Regional | | Azure | Blob Storage Hot | Managed Disks, Standard or Premium | Azure Files, Standard or Premium | | On-premises | Any S3-compatible endpoint, such as MinIO | A local filesystem | NFS or SMB | On Azure, choose the Premium (SSD-backed) tiers rather than Standard if your repositories are very large. Avoid infrequent-access and archival storage classes, such as S3 Glacier, Cloud Storage Nearline and Coldline, and Azure Blob Storage Cool and Archive. Their retrieval characteristics don't suit agentic jobs. For how to configure a backend and set retention, see [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md). ## Scalability * On Kubernetes, each runtime family runs a fixed pool of 2 replicas by default. Autoscaling is off until you enable it, and it needs KEDA installed on the cluster. Once enabled, a family scales on the depth of the job queue rather than on CPU, because a job spends most of its time waiting on the LLM, and it scales out to 25 replicas. It never scales below 2. * On Docker Compose, the pool of runtime containers is fixed. Size it for your peak concurrency, because jobs queue once the pool is full. * Sonar Vortex scales by replica count, from 3 replicas to 20, because each replica serves two concurrent requests. * The Agent Orchestrator isn't on the job execution path, so a single instance serves a growing job volume, and its defaults handle a large number of jobs. ## Resiliency These components are not a high-availability configuration. An interrupted job can be run again, so the priority is protecting job state and storage rather than keeping the components continuously available: * Job state lives in the SonarQube Server database, so your existing database backups cover job history * Shared storage holds job inputs and results. Back it up according to how long you need past results, and monitor free space, because jobs fail when storage is exhausted * If the Agent Orchestrator restarts, jobs in flight fail and can be triggered again. Completed job records are unaffected ## Related pages * [Up to 10 M LOC](/sonarqube-server/server-installation/reference-architectures/up-to-10m-loc.md) * [Up to 50 M LOC](/sonarqube-server/server-installation/reference-architectures/up-to-50m-loc.md) * [Deploying AI agents](/sonarqube-server/server-installation/ai-agents.md) * [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md) * [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.md) * [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md) * [Server host requirements](/sonarqube-server/server-installation/server-host-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.sonarsource.com/sonarqube-server/server-installation/reference-architectures/agentic-features-architecture.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.