> 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/installation-overview.md).

# Installation overview

The components you deploy to run the Hunter Agent, the Remediation Agent, and Vortex analysis on SonarQube Server, 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](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) 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.

{% hint style="info" %}
Enabling the agents is a separate task, covered in [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md) and [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md). Deploy the components first.
{% endhint %}

## Components <a href="#components" id="components"></a>

| Component          | Where it runs                                      | What it does                                                                                                                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 <a href="#how-a-job-runs" id="how-a-job-runs"></a>

```mermaid
%%{init: {'themeVariables': {'primaryColor': 'rgba(18, 110, 211, 0.06)', 'primaryBorderColor': '#126ED3', 'lineColor': '#126ED3'}}}%%
flowchart LR
    SQ["SonarQube Server"]
    AO["Agent Orchestrator"]
    ST[("Shared storage")]
    RT["Agent runtime"]
    VX["Vortex analysis"]
    EP["Egress proxy"]
    LLM["LLM provider"]
    SCM["DevOps platform"]

    SQ -->|"1. trigger job"| AO
    AO -->|"2. check out code"| SCM
    AO -->|"3. stage code"| ST
    AO -->|"4. start job"| RT
    ST -->|"5. read code"| RT
    RT -->|"6. request fixes"| EP
    EP -->|"7. forward"| LLM
    RT -->|"8. verify fix"| EP
    EP -->|"9. forward"| SQ
    SQ -->|"10. analyze fix"| VX
    RT -->|"11. write results"| ST
    ST -->|"12. read results"| AO
    AO -->|"13. publish findings or open PR"| SQ
    RT -.->|"signed calls"| EP
    EP -.->|"signed calls"| SQ
```

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 <a href="#supported-methods" id="supported-methods"></a>

| Method                           | Orchestrator                  | Job capacity                                 |
| -------------------------------- | ----------------------------- | -------------------------------------------- |
| 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.

{% hint style="warning" %}
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.
{% endhint %}

## What depends on what <a href="#dependencies" id="dependencies"></a>

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.

| To run             | You also need                                                |
| ------------------ | ------------------------------------------------------------ |
| 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 <a href="#vortex-analysis" id="vortex-analysis"></a>

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](/sonarqube-server/instance-administration/ai-features/sonar-vortex.md).

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.

{% hint style="info" %}
A degraded state is worth acting on. Unverified fixes are more likely to need changes during review, because nothing has checked them against the rules that raised the issue in the first place.
{% endhint %}

### What it needs <a href="#vortex-requirements" id="vortex-requirements"></a>

| Requirement                | Detail                                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 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 <a href="#storage-capacity" id="storage-capacity"></a>

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](/sonarqube-server/server-installation/ai-agents/shared-storage.md), and monitor it as projects are added.

#### Reverse proxy body size <a href="#reverse-proxy-body-size" id="reverse-proxy-body-size"></a>

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 <a href="#data-lifecycle" id="data-lifecycle"></a>

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 [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#housekeeping).

{% hint style="warning" %}
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.
{% endhint %}

### Keeping analyzer versions aligned <a href="#analyzer-versions" id="analyzer-versions"></a>

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 <a href="#vortex-confirming" id="vortex-confirming"></a>

SonarQube Server polls the service's health endpoint directly and reports the result on the **System** page. See [Verifying the deployment](/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md).

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 <a href="#responsibilities" id="responsibilities"></a>

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

{% hint style="info" %}
Agents never merge their own work. The Remediation Agent opens a pull request for you to review, and the Hunter Agent surfaces findings in SonarQube Server. Configure your DevOps platform to require review, so this stays true.
{% endhint %}

## Deployment roadmap <a href="#roadmap" id="roadmap"></a>

To deploy your agents, work through these steps in order.

| Step | Task                                                                                                                              | Page                                                                                                                                                                                                                                                          |
| ---- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | Check prerequisites: licensing, host requirements, network access, and your LLM provider.                                         | [Before you start](/sonarqube-server/server-installation/ai-agents/before-you-start.md)                                                                                                                                                                       |
| 2    | Install and register the sandbox runtime.                                                                                         | [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)                                                                                                                                                          |
| 3    | Provision shared storage.                                                                                                         | [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md)                                                                                                                                                                |
| 4    | Size the deployment for your workload.                                                                                            | [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.md)                                                                                                                                                                     |
| 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](/sonarqube-server/server-installation/ai-agents/customizing-helm-chart.md) (Kubernetes) or [Deploying with Docker Compose](/sonarqube-server/server-installation/ai-agents/deploying-with-docker-compose.md) (Docker Compose) |
| 6    | Confirm the deployment works.                                                                                                     | [Verifying the deployment](/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md)                                                                                                                                                       |
| 7    | Enable the agents.                                                                                                                | [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md) or [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md)                                                                      |

For the list of component settings, see [Configuration reference](/sonarqube-server/server-installation/ai-agents/configuration-reference.md). If you encounter issues, see [Troubleshooting](/sonarqube-server/server-installation/ai-agents/troubleshooting.md).

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

* [Hunter Agent](/sonarqube-server/instance-administration/ai-features/hunter-agent.md)
* [Remediation Agent](/sonarqube-server/instance-administration/ai-features/remediation-agent.md)
* [Sonar Vortex](/sonarqube-server/instance-administration/ai-features/sonar-vortex.md)
* [Server host requirements](/sonarqube-server/server-installation/server-host-requirements.md)
* [Networking requirements](/sonarqube-server/server-installation/networking-requirements.md)
* [Capacity planning](/sonarqube-server/server-installation/ai-agents/capacity-planning.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.