> 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 running the SonarQube Server AI agents, and the platforms they don't 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>

The Hunter Agent and the 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 the [Sonar product subscriptions](/sonarqube-server/instance-administration/license-management/product-subscriptions.md) page for details about adding the subscription.

Letting your developers trigger Vortex from their own coding agents requires a Vortex subscription as well. Deploying the 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](/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 |
| ZIP installations                   | The sandbox needs a container runtime                                                      |

### 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](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md#on-openshift).

OpenShift applies only to the Helm chart. On Docker Compose and Linux hosts, the agent runtimes use gVisor.

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

Provision one shared storage backend, reachable by both the Agent Orchestrator and the runtime containers. You can use a shared filesystem or S3-compatible object storage. See [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md).

Job artifacts are deleted automatically after 30 days by default. Adjust this in **General Settings** > **Housekeeping** > **Agentic**, see [Setting up shared storage](/sonarqube-server/server-installation/ai-agents/shared-storage.md#housekeeping).

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

The runtime containers run code influenced by a large language model, so their outbound access is deliberately restricted. Allow only what the job needs:

| 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            | Requesting rule details during a run                                                    |
| Remediation Agent runtime | SonarQube Server              | Signed, allowlisted calls to verify fixes and fetch rule descriptions for pull requests |
| Agent runtime             | Vortex analysis               | Verifying proposed fixes                                                                |
| Agent Orchestrator        | Your DevOps platform          | Cloning repositories and opening pull requests                                          |
| Agent Orchestrator        | SonarQube Server              | Reading project data and publishing results                                             |
| 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](/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.

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 isn't 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, so obtaining and installing it on your hosts or nodes is your responsibility.

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](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md).

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

* [Installation overview](/sonarqube-server/server-installation/ai-agents/installation-overview.md)
* [Setting up the sandbox runtime](/sonarqube-server/server-installation/ai-agents/sandbox-runtime.md)
* [Server host requirements](/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.