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 or Up to 50 M LOC, 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.
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.
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
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.
Deployment methods
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.
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.
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.
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.
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:
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.
Sonar Vortex
Sonar Vortex runs continuously rather than per job, and it serves analysis requests from SonarQube Server.
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:
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:
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.
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.
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.
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.
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.
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
Last updated
Was this helpful?