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

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. Add them to your license before you deploy, see the Sonar product subscriptions 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.

Host requirements

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

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.

Unsupported platforms

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
ZIP installations	The sandbox needs a container runtime

OpenShift

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.

Storage

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.

Job artifacts are deleted automatically after 30 days by default. Adjust this in General Settings > Housekeeping > Agentic, see Housekeeping.

Network access

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.

LLM provider

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

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

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

With the prerequisites confirmed, install and register the sandbox runtime. See Setting up the sandbox runtime.

Related pages

• Installation overview

• Setting up the sandbox runtime

• Server host requirements