> 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.

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. 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, or a Kubernetes cluster with containerd |

{% 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                                                           |
| OpenShift                           | OpenShift uses CRI-O, which cannot load the sandbox runtime, and the underlying node filesystem is read-only. See [#openshift](#openshift "mention") |
| ZIP installations                   | The sandbox needs a container runtime                                                                                                                |

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

You cannot run the agent runtimes on OpenShift. The sandbox runtime is not available under CRI-O, so the pods fail to start with a message reporting that the runtime handler cannot be found.

You can still run SonarQube Server itself on OpenShift. If you want to use the AI agents, deploy the Agent Orchestrator and the agent runtimes on a Kubernetes cluster or Linux hosts that meet the host requirements, see [#host-requirements](#host-requirements "mention").

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