> 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 2026.5, and how they fit together.

The Hunter Agent, the Remediation Agent, and Vortex analysis do not 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 is not enough: until you deploy these components, the agents cannot run. See the [Sonar product subscriptions](https://docs.sonarsource.com/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](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/hunter-agent.md) and [Remediation Agent](https://docs.sonarsource.com/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. It also holds the Vortex analysis context, and the job logs that SonarQube Server reads.                                                                                                                           |

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. request repository credentials"| SQ
    AO -->|"3. check out code"| SCM
    AO -->|"4. stage code"| ST
    AO -->|"5. start job"| RT
    ST -->|"6. read code"| RT
    RT -->|"7. request findings or fixes"| EP
    EP -->|"8. forward"| LLM
    RT -->|"9. verify fix, read rule descriptions"| EP
    EP -->|"10. forward"| SQ
    SQ -->|"11. analyze fix"| VX
    VX -->|"12. read what it needs"| SQ
    ST -->|"13. restore analysis context"| VX
    RT -->|"14. write results"| ST
    ST -->|"15. read results"| AO
    AO -->|"16. publish findings"| SQ
    AO -->|"17. open pull request"| SCM
    RT -.->|"renew storage links"| AO
```

The Remediation Agent runtime makes signed calls to SonarQube Server, through the egress proxy, to verify fixes and pull rule descriptions for pull request text. Runtimes call the Orchestrator only to renew expired storage links. To verify a fix, SonarQube Server calls Vortex analysis. Runtimes never call Vortex analysis.

Steps 9 to 13 and 17 apply to the Remediation Agent only, and step 16 to the Hunter Agent only. With object storage, steps 6 and 14 and the storage link renewal also go through the egress proxy. With a shared filesystem, the runtime reads and writes its own mounted folder.

## 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 do not run Kubernetes.

To create the Compose file and its supporting files for your environment, use the [Docker Compose bundle generator](https://github.com/SonarSource/docker-sonarqube/tree/master/agentic-compose-generator). See [Deploying with a Docker installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-docker-installation.md) or, for a ZIP installation, [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md).

{% 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, see [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md).
{% 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](https://docs.sonarsource.com/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](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md), and monitor it as projects are added.

Plan for about 300 MB of analyzer context per project, based on the average number of branches and pull requests per project. Projects with more of either need more. Context stays bounded, because it is purged for old analyses and for anything older than three months. For example, 500 projects need about 150 GB.

#### 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 updates, so do not put it somewhere ephemeral
* Superseded context is cleaned up as newer analyses replace it, so it does not 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](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md#retention).

{% hint style="warning" %}
Do not 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](https://docs.sonarsource.com/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 does not necessarily stop the container, so stop or remove the service yourself if you want to reclaim its resources.

## Who calls whom <a href="#who-calls-whom" id="who-calls-whom"></a>

The components and SonarQube Server call each other in both directions. Each side needs an address that resolves from where it runs. Only the Agent Orchestrator and Vortex analysis publish a port. The runtimes do not.

For every connection and what it's for, see [Before you start](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/before-you-start.md#network-access). For the order of the calls during a job, see [#how-a-job-runs](#how-a-job-runs "mention").

## How the components authenticate <a href="#authentication" id="authentication"></a>

The components authenticate each request with a signature. One shared secret is the source, and a component holds only the keys for the hops it takes part in.

The Agent Orchestrator image derives those keys with `/derive-keys.sh`. Kubernetes and Docker Compose call the same script, so one secret produces the same keys on both. On Kubernetes, the Helm chart derives the keys and you supply the secret. On Docker Compose, the bundle generator creates the secret and derives the keys when the containers start.

| Component                 | Keys it holds                                                                                                                                                     | What it uses them for                                                                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SonarQube Server          | The secret itself, and `agentic-shared`                                                                                                                           | Verifies inbound calls from the Orchestrator, Vortex analysis, and the Remediation Agent runtime. Signs its own calls to the Orchestrator.                                            |
| Agent Orchestrator        | `agentic-shared`, `orchestrator-to-hunter`, `orchestrator-to-remediation`, `hunter-to-orchestrator`, `remediation-to-orchestrator`, `orchestrator-job-capability` | Verifies inbound calls from SonarQube Server and from both runtimes. Signs its own calls to SonarQube Server and its job pushes to each runtime. Issues each job's upload capability. |
| Hunter Agent runtime      | `orchestrator-to-hunter`, `hunter-to-orchestrator`                                                                                                                | Verifies job pushes from the Orchestrator, and signs its own requests back to it.                                                                                                     |
| Remediation Agent runtime | `orchestrator-to-remediation`, `remediation-to-orchestrator`, `remediation-to-sqs`                                                                                | Verifies job pushes from the Orchestrator, signs its own requests back to it, and signs its direct calls to SonarQube Server.                                                         |
| Vortex analysis           | `agentic-shared`                                                                                                                                                  | Signs its calls to SonarQube Server, and verifies SonarQube Server's calls to it.                                                                                                     |

{% hint style="danger" %}
The secret must be at least 32 bytes. A secret shorter than 32 bytes makes SonarQube Server log an error and refuse every signed agentic call, so the agents cannot connect.
{% endhint %}

{% hint style="warning" %}
Never mount the secret itself, or the `orchestrator-job-capability` key, into a runtime container. Runtimes run code influenced by a large language model, and either one would let a job mint credentials for hops it has no part in.
{% endhint %}

SonarQube Server needs the secret file and the derived `agentic-shared` key. The properties are in [Configuration reference](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/configuration-reference.md#server-signing).

To rotate the secret, recreate every component that holds a derived key, including SonarQube Server. Deriving again leaves a running container on the previous key, and requests then fail with `401`. On Docker Compose and on a ZIP installation, you can rotate while components stay up: place the previous secret in a file named after the secret file with a `.previous` suffix before you derive. A verifier accepts both generations until every component has been recreated. Remove the previous generation after that. On Kubernetes, rotating the secret is not supported yet.

## SonarQube Server properties <a href="#sonar-properties" id="sonar-properties"></a>

{% hint style="danger" %}
An environment variable overrides a SonarQube Server property only when that property is a built-in system property, or is already present in `conf/sonar.properties`. None of the agentic properties are built-in system properties. Setting only the environment variable has no effect, and SonarQube Server starts as though the components were never deployed. Declare each property in `conf/sonar.properties`.
{% endhint %}

The property list is in [Configuration reference](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/configuration-reference.md). On Kubernetes, the Helm chart sets the signing properties and the component URLs when you enable the components. You set `sonar.agentic.storage.*` yourself, see [Deploying with a Kubernetes or OpenShift installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-kubernetes-or-openshift-installation.md#storage). On a container image, the configuration directory is read-only at container start, so mount a complete `conf/sonar.properties`. Declaring a property with an empty value is enough to make it overridable from the environment.

## Network boundaries <a href="#network-boundaries" id="network-boundaries"></a>

Kubernetes network policies and the Docker Compose networks enforce the same boundaries:

| Boundary                                                                                                                                 | Why                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The Orchestrator can reach the runtimes                                                                                                  | It pushes jobs to them.                                                                                                                                                                       |
| SonarQube Server cannot reach the runtimes                                                                                               | The runtimes are untrusted, and nothing in SonarQube Server needs to call them.                                                                                                               |
| The runtimes cannot reach SonarQube Server or the database, except the Remediation Agent runtime's signed calls through the egress proxy | The Remediation Agent runtime calls SonarQube Server directly through the egress proxy, to verify fixes and fetch rule descriptions. The Hunter Agent runtime does not call SonarQube Server. |
| The runtimes cannot reach each other                                                                                                     | One job must not be able to observe or disturb another.                                                                                                                                       |
| Only the egress proxy has a route out                                                                                                    | This is what constrains where a job can send data.                                                                                                                                            |

{% hint style="warning" %}
The runtime services verify the Orchestrator's signature on a job push, and that is the authentication on their own endpoints. Their protection is network isolation, so these boundaries are a security control. Do not publish runtime ports, and do not place the runtimes on a network that other workloads can reach.
{% endhint %}

## Trusting a private certificate authority <a href="#private-certificate-authority" id="private-certificate-authority"></a>

When SonarQube Server serves a certificate from your own authority, or outbound traffic passes through a TLS-inspecting proxy, each component has to trust that authority. Each one reads that trust material from a different place:

| Component          | How it trusts the authority                                  |
| ------------------ | ------------------------------------------------------------ |
| Agent Orchestrator | A directory of PEM certificates mounted at `/custom-ca`.     |
| Agent runtimes     | A directory of PEM certificates mounted at `/custom-ca`.     |
| Vortex analysis    | A JVM truststore.                                            |
| SonarQube Server   | A JVM truststore for the web process and the compute engine. |

PEM files for the Agent Orchestrator and the agent runtimes end in `.crt` or `.pem`. Vortex analysis reads only `.crt` files from `/certificates` and skips `.pem`. The authority's `keyUsage` extension includes `keyCertSign`. Vortex analysis and SonarQube Server trust the authority through their JVM truststore.

On Kubernetes, `caCerts` updates the SonarQube Server truststore only. For the Agent Orchestrator's `/custom-ca` directory, the chart has no value, so mount it with `agentOrchestrator.extraVolumes` and `agentOrchestrator.extraVolumeMounts`, and set `agentOrchestrator.containerSecurityContext.readOnlyRootFilesystem` to `false`, because the default read-only root file system makes the Orchestrator exit at start. On Docker Compose, the bundle generator mounts the directory you pass with `--custom-ca-dir`. Pass it as a path relative to the bundle (`./name`), an absolute path, or a path in your home directory (`~/name`). The generator rewrites a bare `name` to `./name`, because Docker Compose would otherwise read it as a named volume. On Windows, write an absolute path with forward slashes, for example `C:/certs`. When the directory is inside the bundle, the generator creates it. Create a directory outside the bundle yourself. Put your `.crt` or `.pem` files in it before you run `docker compose up -d`. The generator warns when the directory does not exist or holds no CA file. A connection that needs a missing CA fails with `PKIX path building failed`. When that connection is the database connection, the Agent Orchestrator exits at start. With `--custom-ca-dir`, the generator omits `read_only: true` on the Orchestrator so it can update the JVM truststore. The certificate mount stays read-only.

## Traffic between components <a href="#traffic" id="traffic"></a>

Traffic between the Orchestrator, the runtimes, and Vortex analysis is unencrypted when those components sit together on an internal network. Each request is authenticated by signature. Traffic that leaves the host can use TLS: put SonarQube Server behind TLS and the components reach it over HTTPS.

To encrypt the published Orchestrator and Vortex analysis ports as well, terminate TLS in front of them and give SonarQube Server the issuing authority. On Kubernetes, see [Deploying with a Kubernetes or OpenShift installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-kubernetes-or-openshift-installation.md#tls).

## Job timeouts <a href="#timeouts" id="timeouts"></a>

Four settings bound how long a job may run, and they have to stay in order. Nothing checks the Orchestrator timeout against the runtime timeout.

| Setting                                                                                        | Who changes it                                                                       | Bounds                                                                                  | Hunter default     | Remediation default |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------ | ------------------- |
| `SCRIPT_TIMEOUT_SECONDS`                                                                       | You, as an environment variable on the runtime, on Docker Compose and on Kubernetes. | How long the agent itself may run before the runtime stops it.                          | `43200` (12 hours) | `900` (15 minutes)  |
| `SHUTDOWN_GRACE_SECONDS`                                                                       | The runtime image. Do not set it. The Helm chart does not set it.                    | How long shutdown waits for an in-flight job to finish.                                 | `43800`            | `2100`              |
| `LIVENESS_JOB_MAX_SECONDS`                                                                     | The runtime image. Do not set it. The Helm chart does not set it.                    | When a job counts as stuck rather than slow, at which point the container is restarted. | `46800`            | `2700`              |
| `sonar.agentic.orchestrator.watcher.hunter-timeout-seconds` and `.remediation-timeout-seconds` | You, on the Orchestrator.                                                            | How long the Orchestrator waits before marking a job failed.                            | `44400`            | `3600`              |

Keep them in ascending order on each runtime, and keep the Orchestrator's timeout above the runtime's script timeout. A grace period below the script timeout means a job in flight at shutdown is killed rather than finished. An Orchestrator timeout below the script timeout means the Orchestrator gives up on a job that is still working.

On Kubernetes, the chart sets `terminationGracePeriodSeconds` and leaves `SHUTDOWN_GRACE_SECONDS` and `LIVENESS_JOB_MAX_SECONDS` to the image, see [Deploying with a Kubernetes or OpenShift installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-kubernetes-or-openshift-installation.md#stop-grace). On Docker Compose, the generator sets `stop_grace_period` above each component's drain and leaves those two to the image, see [Deploying with a Docker installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-docker-installation.md#stop-grace).

## Sandbox and storage <a href="#sandbox-and-storage" id="sandbox-and-storage"></a>

Each runtime asks for the `runsc` sandbox. When `runsc` is not registered, the container refuses to start. Docker cannot cap a container's disk usage on its own, so the sandbox provides a bounded writable overlay. See [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md).

SonarQube Server, the Orchestrator, the runtimes, and Vortex analysis share one storage backend, either object storage (Amazon S3 or S3-compatible, Azure Blob Storage, or Google Cloud Storage) or a filesystem. Vortex analysis reads the same location SonarQube Server writes analysis context to. See [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md).

## 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](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/before-you-start.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 2    | Install and register the sandbox runtime.                                                                                         | [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 3    | Provision shared storage.                                                                                                         | [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 4    | Size the deployment for your workload.                                                                                            | [Capacity planning](https://docs.sonarsource.com/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 a Kubernetes or OpenShift installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-kubernetes-or-openshift-installation.md) or [Deploying with a Docker installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-with-docker-installation.md). If SonarQube Server runs from the ZIP file, see [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md). On Windows, see [Deploying on Windows](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-on-windows.md) |
| 6    | Confirm the deployment works.                                                                                                     | [Verifying the deployment](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/verifying-the-deployment.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 7    | Enable the agents.                                                                                                                | [Hunter Agent](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/hunter-agent.md) or [Remediation Agent](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/remediation-agent.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

To monitor the components once they run, see [Monitoring the agentic components](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/monitoring-agentic-components.md). To update them later, see [Updating the agentic components](https://docs.sonarsource.com/sonarqube-server/server-update-and-maintenance/update/updating-agentic-components.md). For the list of component settings, see [Configuration reference](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/configuration-reference.md). If you encounter issues, see [Troubleshooting](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/troubleshooting.md).

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

* [Hunter Agent](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/hunter-agent.md)
* [Remediation Agent](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/remediation-agent.md)
* [Sonar Vortex](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/sonar-vortex.md)
* [Server host requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/server-host-requirements.md)
* [Networking requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/networking-requirements.md)
* [Capacity planning](https://docs.sonarsource.com/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 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/installation-overview.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.
