> 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/before-you-start.md).

# Before you start

Host, storage, network, and licensing prerequisites for the AI agents, and the platforms they do not support. This page is for SonarQube Server 2026.5.

Check every prerequisite on this page before you deploy. Several of them cannot be added afterward without redeploying.

## Licensing <a href="#licensing" id="licensing"></a>

Hunter Agent and Remediation Agent each require a separate subscription alongside your SonarQube Server edition. To trial or purchase Hunter Agent or Remediation Agent, contact [our Sales team](https://www.sonarsource.com/products/sonarqube/contact-sales/). Add them to your license before you deploy, see [Sonar product subscriptions](https://docs.sonarsource.com/sonarqube-server/instance-administration/license-management/product-subscriptions.md).

Letting your developers trigger Sonar Vortex from their own coding agents requires a Sonar Vortex subscription as well. Deploying Remediation Agent always deploys the Vortex analysis component it depends on, but that alone does not entitle direct use from the SonarQube CLI or the SonarQube MCP Server. See [Sonar Vortex](https://docs.sonarsource.com/sonarqube-server/instance-administration/ai-features/sonar-vortex.md).

## Host requirements <a href="#host-requirements" id="host-requirements"></a>

Each agentic job runs in a sandboxed container, and the sandbox has specific host requirements.

| Requirement       | Detail                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating system  | Linux. Any current distribution                                                                                                                           |
| Kernel            | 4.14.77 or later                                                                                                                                          |
| Architecture      | x86-64 or ARM64, running natively                                                                                                                         |
| Container runtime | Docker Engine on a Linux host, a Kubernetes cluster with containerd, or an OpenShift cluster with Kata Containers, see [#openshift](#openshift "mention") |

{% hint style="danger" %}
The host architecture must match the container image architecture. The sandbox cannot run under emulation, so an x86-64 image on an ARM64 host fails immediately with `exec format error`, even where emulation would normally let it run.
{% endhint %}

### Unsupported platforms <a href="#unsupported-platforms" id="unsupported-platforms"></a>

These platforms are unsupported for the AI agents only. SonarQube Server itself continues to run on every platform covered by its own installation requirements, including a ZIP installation.

| Platform                                 | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Docker Desktop, on macOS or Windows      | Docker Desktop provides no supported way to register the sandbox runtime. Use a Linux host. To evaluate on macOS or Windows without a sandbox, see [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#without-sandbox). For Windows, see also [Deploying on Windows](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-on-windows.md) |
| The components installed from a ZIP file | The sandbox needs a container runtime. You can still deploy the components as containers alongside a ZIP installation, see [Deploying alongside a ZIP installation](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/deploying-alongside-zip-installation.md)                                                                                                                                                               |

### OpenShift <a href="#openshift" id="openshift"></a>

You can run the agent runtimes on OpenShift 4.19 to 4.22 with the Helm chart. gVisor is not available on OpenShift, because CRI-O cannot use the `runsc` runtime, so the chart sandboxes the agent runtimes with Kata Containers instead. This requires:

* The OpenShift sandboxed containers operator, installed before you deploy. It provides the `kata` RuntimeClass, or the `kata-remote` RuntimeClass for peer pods. The chart does not create the RuntimeClass, and the installation fails if it's missing
* Bare-metal Red Hat Enterprise Linux CoreOS (RHCOS) worker nodes for the `kata` RuntimeClass. On cloud VMs on AWS, Azure, or Google Cloud, use peer pods with the `kata-remote` RuntimeClass

The other prerequisites are the same as on Kubernetes, including an external database, shared storage, and the shared signing secret. For the Helm values, see [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#on-openshift).

OpenShift applies only to the Helm chart. Everywhere else, the agent runtimes use gVisor by default. On Kubernetes, you can use another sandboxed runtime class instead, see [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#another-runtime).

## Database <a href="#database" id="database"></a>

The Agent Orchestrator connects to the SonarQube Server database to track job state, so SonarQube Server must use an external database that the Orchestrator can reach over the network. The Docker Compose bundle generator supports PostgreSQL, either bundled or external.

If you deploy with Docker Compose and generate your bundle with `--db external`, both SonarQube Server and the Orchestrator always connect with `sslmode=verify-full`. Your database must serve TLS with a certificate that is valid for its host name, and that both sides trust. SonarQube Server validates that certificate against its JVM truststore. The certificate authority must be in the JDK `cacerts`, or in the truststore set with `-Djavax.net.ssl.trustStore` on `sonar.web.javaAdditionalOpts` and `sonar.ce.javaAdditionalOpts`. If the bundle runs SonarQube Server, that container trusts public certificate authorities only.

## Storage <a href="#storage" id="storage"></a>

Provision one shared storage backend, reachable by SonarQube Server, the Agent Orchestrator, Vortex analysis, and the runtime containers. You can use a shared filesystem or object storage: Amazon S3 or any S3-compatible endpoint, Azure Blob Storage, or Google Cloud Storage. See [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md).

Job artifacts are deleted automatically after 30 days by default. To change it, go to **Administration** > **Configuration** > **General settings** > **Housekeeping** > **Agentic**, see [Setting up shared storage](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/shared-storage.md#retention).

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

Allow these connections between the components, SonarQube Server, and your services. The runtime containers run code influenced by a large language model, so allow nothing else from them:

| From                      | To                            | For                                                                                         |
| ------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
| Agent runtime             | Your LLM provider             | Generating findings and fixes                                                               |
| Agent runtime             | Shared storage                | Reading staged code and writing results                                                     |
| Agent runtime             | Agent Orchestrator            | Renewing expired storage links during a run                                                 |
| Remediation Agent runtime | SonarQube Server              | Signed, allowlisted calls to verify fixes and fetch rule descriptions for pull requests     |
| SonarQube Server          | Agent Orchestrator            | Triggering jobs and polling component health for the **System** page                        |
| SonarQube Server          | Vortex analysis               | Verifying proposed fixes                                                                    |
| SonarQube Server          | Shared storage                | Writing analysis context and reading agent job logs                                         |
| Vortex analysis           | SonarQube Server              | Reading what it needs to analyze                                                            |
| Vortex analysis           | Shared storage                | Restoring analysis context                                                                  |
| Agent Orchestrator        | Shared storage                | Staging source code, collecting results, and deleting expired artifacts                     |
| Agent Orchestrator        | Your DevOps platform          | Cloning repositories and opening pull requests                                              |
| Agent Orchestrator        | SonarQube Server              | Reading project data, requesting short-lived repository credentials, and publishing results |
| Agent Orchestrator        | Your LLM provider             | Scheduled Remediation Agent runs, when you bring your own provider                          |
| Agent Orchestrator        | The SonarQube Server database | Tracking job state                                                                          |

Block everything else leaving the runtime containers. Except for the Remediation Agent runtime's signed, allowlisted calls, the runtimes must not reach SonarQube Server or the database directly.

For the rest of the SonarQube Server network requirements, see [Networking requirements](https://docs.sonarsource.com/sonarqube-server/server-installation/networking-requirements.md).

## LLM provider <a href="#llm-provider" id="llm-provider"></a>

Register an LLM provider and select a model before you enable an agent. You do this once, under **Administration** > **Configuration** > **AI capabilities** > **LLM providers**, and all AI capabilities share the registry.

Set up the settings encryption key before you register the provider. SonarQube Server uses it to encrypt the provider's secrets when you save the provider. Without a key, it stores them in plaintext, and registration still succeeds. The Agent Orchestrator decrypts the secrets with the same key, so it needs a copy too. Keep the key once you've registered a provider: if it changes, SonarQube Server can no longer decrypt the stored secrets. See [Sensitive settings](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/encrypting-settings.md).

The agents cannot run without a provider, and the enablement toggles stay locked until you save a provider and a model.

## Projects <a href="#projects" id="projects"></a>

For each project you want an agent to work on:

* Bind the project to a repository on your DevOps platform. The agents clone the repository, so they cannot run on a project that is not bound
* Analyze the project, so the agents have issues to work from

## Air-gapped environments <a href="#air-gapped" id="air-gapped"></a>

You can run the AI agents without internet access to Sonar, but you must supply the sandbox runtime yourself. Sonar does not mirror it or provide a side-loading package. The files to copy, and the install steps for a Docker host and for Kubernetes, are in [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#air-gapped).

Your LLM provider must also be reachable from the runtime containers, which means either a provider hosted inside your network or an approved route out to a hosted one.

## Next step <a href="#next-step" id="next-step"></a>

With the prerequisites confirmed, install and register the sandbox runtime. See [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md).

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

* [Installation overview](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/installation-overview.md)
* [Setting up the sandbox runtime](https://docs.sonarsource.com/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)
* [Server host requirements](https://docs.sonarsource.com/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/ai-agents/before-you-start.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.
