Installation overview
The components you deploy to run the Hunter Agent, the Remediation Agent, and Vortex analysis on SonarQube Server 2026.5, and how they fit together.
The Hunter Agent, the Remediation Agent, and Vortex analysis don't run inside SonarQube Server. They run as separate containers that you deploy alongside it, on your own infrastructure. Adding the agents to your license and enabling them in the UI isn't enough: until you deploy these components, the agents cannot run. See the Sonar product subscriptions page for details about adding the subscriptions.
This section covers what to deploy, what each component needs from you, and how to confirm it works.
Components
Agentic API
Inside SonarQube Server
Exposes the agents to the UI and to automation. No separate deployment.
Agent Orchestrator
Standalone container
Coordinates the whole job lifecycle: checks out your source code, stages it, hands the job to an agent runtime, tracks progress, then processes the results.
Agent runtime
Long-lived; each replica runs one job at a time
Runs agentic jobs in a sandbox. Reads the staged code, calls your LLM provider, and writes its results back to storage.
Vortex analysis
Standalone container
Analyzes single files on demand, reusing context collected during CI analysis. The Remediation Agent uses it to verify its own fixes before opening a pull request.
Egress proxy
Standalone container, fixed high-availability pair
Carries all outbound traffic from the runtime containers: requests to the LLM provider and storage, calls to the Orchestrator and, for the Remediation Agent only, calls to SonarQube Server. Kubernetes network policies cannot filter by domain name, so the proxy gives you one place to enforce and audit egress.
Shared storage
Your infrastructure
Carries source code snapshots and job results between the Orchestrator and the runtime containers.
The Agent Orchestrator is shared. One Orchestrator serves both the Hunter Agent and the Remediation Agent, so you deploy it once regardless of how many agents you use.
How a job runs
Rule lookups during a run go through the Orchestrator, which fetches the data from SonarQube Server on the job's behalf. The Remediation Agent runtime is an exception: it also makes signed calls to SonarQube Server, through the egress proxy, to verify fixes and pull rule descriptions for pull request text. To verify a fix, SonarQube Server calls Vortex analysis.
Supported deployment methods
Kubernetes, using the Helm chart
Runs as a Deployment.
Fixed pool by default; optional autoscaling.
Docker Compose
Runs as a long-lived service.
Fixed pool.
Kubernetes is the recommended method for production. Docker Compose is the supported method for environments that don't run Kubernetes.
The AI agents cannot run from a ZIP installation. They need a container runtime to provide the per-job sandbox, so there is no ZIP equivalent. You can still run SonarQube Server itself from a ZIP file and deploy these components separately as containers.
What depends on what
On Kubernetes, the Helm chart validates deployment and some components cannot run without their dependencies. Docker Compose has no equivalent check, so you define every dependency yourself.
Hunter Agent
Agent Orchestrator.
Remediation Agent
Agent Orchestrator and Vortex analysis.
Agent Orchestrator
Access to the SonarQube Server database, and shared storage.
Sandbox isolation
At least one agent runtime.
Vortex analysis
Vortex analysis is an on-demand analysis service. Where a CI analysis scans a whole project, Vortex analysis analyzes a single file or a small set of files, and does it fast enough to be called during an agent's work.
It reaches CI-level precision on a single file by reusing context. During a normal CI analysis, the analyzers collect the context they need, such as dependencies, compiled artifacts, and metadata. Vortex analysis stores that context and restores it later, when something asks it to analyze one file. That's why it needs storage, and why it needs projects to have been analyzed first.
Vortex analysis is a long-lived service that runs continuously alongside SonarQube Server.
Two different things call it. Deploying Vortex analysis is what activates it for the Remediation Agent's use, covered by the Remediation Agent subscription, with no separate instance-admin enable step. Your developers' coding agents can also call it directly through the SonarQube CLI or the SonarQube MCP Server, which needs a separate Vortex subscription and does need deployment and enablement on the instance. See Sonar Vortex.
The Remediation Agent calls Vortex analysis to check its own work. When the agent produces a fix, Vortex analysis analyzes the result, so the agent can confirm the fix resolves the issue without introducing a new one. On Kubernetes, deploying the Remediation Agent without Vortex analysis fails chart validation, because verification is part of how the agent works rather than an optional extra.
If Vortex analysis becomes unavailable after deployment, the Remediation Agent keeps running in a degraded state: it still proposes fixes and opens pull requests, but those fixes are not verified by analysis first. SonarQube Server warns administrators when this happens.
What it needs
Storage
The same storage SonarQube Server writes analysis context to. Both must point at the same location.
Access to SonarQube Server
A signing key derived from the shared agentic secret, so it can authenticate to read what it needs to analyze.
Analyzed projects
Context is collected during CI analysis, so a project that has never been analyzed has no context to restore.
Storage capacity
Analyzer context is significantly larger than agent job artifacts, because it holds what the analyzers need to reproduce their CI behavior rather than a patch and a log. Size this storage separately from the job artifact figures in Setting up shared storage, and monitor it as projects are added.
Reverse proxy body size
The scanner uploads analyzer context to SonarQube Server during CI analysis. For a large project, that upload can exceed the default body-size limit of a reverse proxy or gateway in front of SonarQube Server, and the scanner's own execution log shows an HTTP 413 for the rejected upload. The scanner treats this as non-fatal, so analysis still succeeds and the failure does not surface as a build failure. The context is simply missing, and Vortex analysis and the Remediation Agent's fix verification lose precision as a result.
If you deploy SonarQube Server behind a reverse proxy or ingress, confirm it allows a request body large enough for your largest projects' analyzer context, not just for typical API traffic.
Data lifecycle
Vortex analysis manages its own data lifecycle, and it differs from agent job retention in both directions:
Context must persist across restarts and upgrades, so don't put it somewhere ephemeral
Superseded context is cleaned up as newer analyses replace it, so it doesn't grow without limit the way unmanaged job artifacts do
The deleteOlderThan housekeeping settings apply to agent job artifacts only, not to Vortex analysis context, see Housekeeping.
Don't apply the short lifecycle policy you use for agent job artifacts to the Vortex analysis location. Deleting context that's still current forces analyses to run without it, which costs you the precision you deployed the service for.
Keeping analyzer versions aligned
Vortex analysis runs analyzers of its own, and they should stay aligned with the analyzer versions your SonarQube Server deployment uses. When the two drift, the same file can produce different results depending on which path analyzed it. Update Vortex analysis alongside SonarQube Server rather than independently.
Confirming it's running
SonarQube Server polls the service's health endpoint directly and reports the result on the System page. See Verifying the deployment.
Errors from Vortex analysis appear in the SonarQube Server web.log, not in the per-job agent logs.
Disabling Vortex analysis stops SonarQube Server from sending it new requests. It doesn't necessarily stop the container, so stop or remove the service yourself if you want to reclaim its resources.
Who is responsible for what
Sonar provides the container images, the sandbox model, the hardened runtime image, and a software bill of materials with vulnerability scan results for each release.
You are responsible for:
The hosts or cluster the components run on, and their network access
Provisioning shared storage
Installing and maintaining the sandbox runtime on your hosts or nodes
Restricting outbound network access from the runtime containers
Requiring review before anyone merges a pull request an agent opens
Deployment roadmap
To deploy your agents, work through these steps in order.
1
Check prerequisites: licensing, host requirements, network access, and your LLM provider.
5
Deploy the components you need: the Agent Orchestrator, the agent runtimes, and Vortex analysis if you use the Remediation Agent.
Deploying with the Helm chart (Kubernetes) or Deploying with Docker Compose (Docker Compose)
For the list of component settings, see Configuration reference. If you encounter issues, see Troubleshooting.
Related pages
Last updated
Was this helpful?